@akanjs/devkit 2.3.9-rc.4 → 2.3.9-rc.5

package/devkitUtils.test.ts

@@ -269,11 +269,11 @@ describe("getModelFileData", () => {
         ].join("\n"),
       );
       await write(
-        path.join(root, "apps/demo/lib/post/post.Unit.tsx"),
+        path.join(root, "apps/demo/lib/post/Post.Unit.tsx"),
         "export default function Unit() { return null; }\n",
       );
       await write(
-        path.join(root, "apps/demo/lib/post/post.View.tsx"),
+        path.join(root, "apps/demo/lib/post/Post.View.tsx"),
         "export default function View() { return null; }\n",
       );
 

package/executors.ts

@@ -626,14 +626,14 @@ export class Executor {
       overwrite?: boolean;
     },
     dict: { [key: string]: string } = {},
-    options: { [key: string]: any } = {},
+    options: { [key: string]: unknown } = {},
   ): Promise<FileContent | null> {
     if (targetPath.endsWith(".ts") || targetPath.endsWith(".tsx")) {
       const getContent = (await import(templatePath)) as {
         default: (
           scanInfo: AppInfo | LibInfo | null,
           dict: { [key: string]: string },
-          options?: { [key: string]: any },
+          options?: { [key: string]: unknown },
         ) => Promise<string | null | { filename: string; content: string }>;
       };
       const result = await getContent.default(scanInfo ?? null, dict, options);
@@ -686,7 +686,7 @@ export class Executor {
     template: string;
     scanInfo?: AppInfo | LibInfo | null;
     dict?: { [key: string]: string };
-    options?: { [key: string]: any };
+    options?: { [key: string]: unknown };
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
@@ -752,7 +752,7 @@ export class Executor {
     basePath: string;
     template: string;
     dict?: { [key: string]: string };
-    options?: { [key: string]: any };
+    options?: { [key: string]: unknown };
     overwrite?: boolean;
   }): Promise<FileContent[]> {
     const dict = {
@@ -827,10 +827,10 @@ export class Executor {
     filePath: string,
     { fix = false, dryRun = false }: { fix?: boolean; dryRun?: boolean } = {},
   ): Promise<{
-    results: any[]; // ESLint.LintResult[];
+    results: unknown[]; // ESLint.LintResult[];
     message: string;
-    errors: any[]; // ESLintLinter.LintMessage[];
-    warnings: any[]; // ESLintLinter.LintMessage[];
+    errors: unknown[]; // ESLintLinter.LintMessage[];
+    warnings: unknown[]; // ESLintLinter.LintMessage[];
   }> {
     const path = this.getPath(filePath);
     const linter = this.getLinter();
@@ -1225,40 +1225,44 @@ export class SysExecutor extends Executor {
   async getViewComponents() {
     const viewComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.View.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.View.tsx`).exists());
     return viewComponents;
   }
 
   async getUnitComponents() {
     const unitComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.Unit.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.Unit.tsx`).exists());
     return unitComponents;
   }
   async getTemplateComponents() {
     const templateComponents = (await this.readdir("lib"))
       .filter((name) => !name.startsWith("_") && !name.startsWith("__") && !name.endsWith(".ts"))
-      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${name}.Template.tsx`).exists());
+      .filter((name) => Bun.file(`${this.cwdPath}/lib/${name}/${capitalize(name)}.Template.tsx`).exists());
     return templateComponents;
   }
 
   async getViewsSourceCode() {
     const viewComponents = await this.getViewComponents();
     return Promise.all(
-      viewComponents.map((viewComponent) => this.getLocalFile(`lib/${viewComponent}/${viewComponent}.View.tsx`)),
+      viewComponents.map((viewComponent) =>
+        this.getLocalFile(`lib/${viewComponent}/${capitalize(viewComponent)}.View.tsx`),
+      ),
     );
   }
   async getUnitsSourceCode() {
     const unitComponents = await this.getUnitComponents();
     return Promise.all(
-      unitComponents.map((unitComponent) => this.getLocalFile(`lib/${unitComponent}/${unitComponent}.Unit.tsx`)),
+      unitComponents.map((unitComponent) =>
+        this.getLocalFile(`lib/${unitComponent}/${capitalize(unitComponent)}.Unit.tsx`),
+      ),
     );
   }
   async getTemplatesSourceCode() {
     const templateComponents = await this.getTemplateComponents();
     return Promise.all(
       templateComponents.map((templateComponent) =>
-        this.getLocalFile(`lib/${templateComponent}/${templateComponent}.Template.tsx`),
+        this.getLocalFile(`lib/${templateComponent}/${capitalize(templateComponent)}.Template.tsx`),
       ),
     );
   }

package/getModelFileData.ts

@@ -1,3 +1,5 @@
+import { capitalize } from "akanjs/common";
+
 interface ModelFileData {
   moduleType: "lib" | "app";
   moduleName: string;
@@ -16,9 +18,10 @@ interface ModelFileData {
 export const getModelFileData = async (modulePath: string, modelName: string): Promise<ModelFileData> => {
   const moduleType = modulePath.startsWith("apps") ? "app" : "lib";
   const moduleName = modulePath.split("/")[1] ?? "";
+  const modelComponentName = capitalize(modelName);
   const constantFilePath = `${modulePath}/lib/${modelName}/${modelName}.constant.ts`;
-  const unitFilePath = `${modulePath}/lib/${modelName}/${modelName}.Unit.tsx`;
-  const viewFilePath = `${modulePath}/lib/${modelName}/${modelName}.View.tsx`;
+  const unitFilePath = `${modulePath}/lib/${modelName}/${modelComponentName}.Unit.tsx`;
+  const viewFilePath = `${modulePath}/lib/${modelName}/${modelComponentName}.View.tsx`;
   const [constantFileStr, unitFileStr, viewFileStr] = await Promise.all([
     Bun.file(constantFilePath).text(),
     Bun.file(unitFilePath).text(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.4",
+  "version": "2.3.9-rc.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.4",
+    "akanjs": "2.3.9-rc.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/artifacts.ts

@@ -186,6 +186,15 @@ const statusForScope = (
   return hasScopeFailure(scopes, expectedScope, diagnostics) ? "failed" : "passed";
 };
 
+const statusForValidationKind = (
+  commands: readonly WorkflowValidationCommandResult[],
+  kind: WorkflowValidationCommandResult["kind"],
+): WorkflowValidationStatus => {
+  const matching = commands.filter((command) => command.kind === kind);
+  if (matching.length === 0) return "unknown";
+  return matching.some((command) => command.status === "failed") ? "failed" : "passed";
+};
+
 const createKnownBlockers = (
   commands: readonly WorkflowValidationCommandResult[],
   diagnostics: readonly WorkflowDiagnostic[],
@@ -251,7 +260,17 @@ const createValidationStatuses = (
         : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
           ? "failed"
           : "passed";
-  return { sourceStatus, workspaceStatus, overallStatus };
+  return {
+    sourceStatus,
+    workspaceStatus,
+    overallStatus,
+    summary: {
+      sourceChange: sourceStatus,
+      generatedSync: statusForValidationKind(commands, "sync"),
+      workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),
+      environment: statusForScope(commands, diagnostics, scopes, "environment"),
+    },
+  };
 };
 
 export const createWorkflowValidationRunReport = async ({

package/workflow/executor.ts

@@ -2,6 +2,7 @@ import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
 import { AppExecutor, LibExecutor } from "../executors";
 import { createWorkflowApplyReport, workflowCommandsForPlan } from "./artifacts";
+import { moduleSourcePaths } from "./source";
 import type {
   PrimitiveChangedFile,
   PrimitiveGeneratedFile,
@@ -16,6 +17,7 @@ import type {
   WorkflowStepRegistry,
   WorkflowStepResult,
 } from "./types";
+import { addFieldUiPolicyForType } from "./uiPolicy";
 
 export const workflowStepKey = (workflow: string, stepId: string) => `${workflow}:${stepId}`;
 
@@ -31,6 +33,8 @@ export const primitiveReportToWorkflowStepResult = (report: PrimitiveWriteReport
 const workflowStringInput = (value: WorkflowInputValue | undefined) => (typeof value === "string" ? value : null);
 const workflowStringListInput = (value: WorkflowInputValue | undefined) =>
   Array.isArray(value) ? value.join(",") : null;
+const workflowStringArrayInput = (value: WorkflowInputValue | undefined) => (Array.isArray(value) ? value : null);
+const workflowBooleanInput = (value: WorkflowInputValue | undefined) => (typeof value === "boolean" ? value : null);
 
 const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
   if (!target) return null;
@@ -66,22 +70,22 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   const module = workflowStringInput(plan.inputs.module) ?? "<module>";
   const field = workflowStringInput(plan.inputs.field) ?? "<field>";
   const typeName = workflowStringInput(plan.inputs.type);
-  const isNumeric = typeName === "Int" || typeName === "Float" || typeName === "integer" || typeName === "float";
+  const policy = addFieldUiPolicyForType(typeName ?? "String");
+  const surfaces = workflowStringArrayInput(plan.inputs.surfaces);
+  const templateRequested = surfaces?.includes("template") ?? false;
   const moduleClassName = capitalize(module);
-  const target = `${app ? `apps/${app}` : "*"}/lib/${module}/${moduleClassName}.Template.tsx`;
+  const target = `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`;
   return {
     recommendations: [
       {
         code: "add-field-ui-surface-review",
         kind: "manual-action",
         target,
-        action: isNumeric
-          ? `Review ${moduleClassName} Template/Unit/View/Store surfaces before adding ${field}; confirm the local Field.Text numeric parser/formatter, validation rule, and dictionary label pattern.`
-          : `Add ${field} to ${moduleClassName} UI surfaces only when the local Field.* pattern is clear.`,
+        action: templateRequested
+          ? `Template was requested for ${field}. If no Template file changed, auto-edit was skipped because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Candidate position: inside Layout.Template near the existing Field components.`
+          : `Template was not selected, so UI files are intentionally left unchanged. Candidate positions if you expose it later: Layout.Template field list for editing, Light${moduleClassName} projection for list/card data, and Unit/View card sections for display.`,
         confidence: "medium",
-        message: isNumeric
-          ? `No UI file was modified automatically because a safe numeric input component pattern is not yet detected for ${module}.${field}.`
-          : `Review Template/Unit/View/Store surfaces for ${module}.${field}; no UI file was modified automatically.`,
+        message: `Review UI surfaces for ${module}.${field}; recommended component is ${policy.component}, with manual reasons and candidate positions in action.`,
       },
     ],
     nextActions: [
@@ -149,6 +153,8 @@ export const createWorkflowStepRegistry = ({
             field: workflowStringInput(plan.inputs.field),
             values: workflowStringListInput(plan.inputs.values),
             defaultValue: workflowStringInput(plan.inputs.default),
+            surfaces: workflowStringArrayInput(plan.inputs.surfaces),
+            includeInLight: workflowBooleanInput(plan.inputs.includeInLight),
           }),
         );
       }
@@ -159,6 +165,8 @@ export const createWorkflowStepRegistry = ({
           field: workflowStringInput(plan.inputs.field),
           type: workflowStringInput(plan.inputs.type),
           defaultValue: workflowStringInput(plan.inputs.default),
+          surfaces: workflowStringArrayInput(plan.inputs.surfaces),
+          includeInLight: workflowBooleanInput(plan.inputs.includeInLight),
         }),
       );
     },

package/workflow/index.ts

@@ -5,4 +5,5 @@ export * from "./primitive";
 export * from "./render";
 export * from "./source";
 export * from "./types";
+export * from "./uiPolicy";
 export * from "./utils";

package/workflow/plan.ts

@@ -1,5 +1,5 @@
 import { capitalize } from "akanjs/common";
-import { normalizeFieldType } from "./source";
+import { coerceFieldDefault, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
   WorkflowInputSpec,
@@ -10,6 +10,7 @@ import type {
   WorkflowSpec,
   WorkflowSurfaceMode,
 } from "./types";
+import { addFieldUiPolicyForType } from "./uiPolicy";
 
 const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
 
@@ -31,6 +32,14 @@ const normalizeInputValue = (name: string, spec: WorkflowInputSpec, value: unkno
     const values = parseStringList(value);
     return values && values.length > 0 ? values : null;
   }
+  if (spec.type === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (typeof value !== "string") return null;
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "true") return true;
+    if (lowered === "false") return false;
+    return null;
+  }
   if (typeof value === "string" && surfaceModes.has(value as WorkflowSurfaceMode)) return value as WorkflowSurfaceMode;
   throw new Error(`Unsupported workflow input value for ${name}`);
 };
@@ -44,13 +53,47 @@ export const getWorkflowSpec = (specs: readonly WorkflowSpec[], name: string) =>
 export const compactWorkflowInputs = (inputs: WorkflowPlanInputs) =>
   Object.fromEntries(Object.entries(inputs).filter(([, value]) => value !== null && value !== ""));
 
-const addFieldComponentForType = (typeName: string) => {
-  const normalizedType = normalizeFieldType(typeName);
-  if (normalizedType === "Boolean") return "Field.ToggleSelect";
-  if (normalizedType === "Date") return "Field.Date";
-  if (normalizedType === "Int" || normalizedType === "Float") return "manual numeric input review";
-  if (typeName.toLowerCase() === "enum") return "Field.ToggleSelect";
-  return "Field.Text";
+const addFieldTargetRoot = (app: string | null) => (app ? `apps/${app}` : "*");
+
+const addFieldPaths = (inputs: Record<string, WorkflowInputValue>) => {
+  const app = typeof inputs.app === "string" ? inputs.app : null;
+  const module = typeof inputs.module === "string" ? inputs.module : "<module>";
+  const paths = moduleSourcePaths(module);
+  const root = addFieldTargetRoot(app);
+  return {
+    constant: `${root}/${paths.constant}`,
+    dictionary: `${root}/${paths.dictionary}`,
+    template: `${root}/${paths.template}`,
+    unit: `${root}/${paths.unit}`,
+    view: `${root}/${paths.view}`,
+  };
+};
+
+const selectedAddFieldSurfaces = (inputs: Record<string, WorkflowInputValue>) =>
+  Array.isArray(inputs.surfaces) ? new Set(inputs.surfaces) : null;
+
+const addFieldDefaultCoercion = (inputs: Record<string, WorkflowInputValue>) => {
+  const typeName = typeof inputs.type === "string" ? inputs.type : null;
+  const defaultValue = typeof inputs.default === "string" ? inputs.default : null;
+  if (!typeName || defaultValue === null) return null;
+  if (typeName.toLowerCase() === "number" || typeName.toLowerCase() === "numeric") return null;
+  const enumValues = Array.isArray(inputs.values) ? inputs.values : null;
+  return coerceFieldDefault(typeName.toLowerCase() === "enum" ? "enum" : typeName, defaultValue, { enumValues });
+};
+
+const createAddFieldDefaultRecommendations = (inputs: Record<string, WorkflowInputValue>): WorkflowRecommendation[] => {
+  const field = typeof inputs.field === "string" ? inputs.field : "<field>";
+  const coercion = addFieldDefaultCoercion(inputs);
+  if (!coercion?.normalized || !coercion.expression) return [];
+  return [
+    {
+      code: "add-field-default-normalized",
+      kind: "manual-action",
+      confidence: "high",
+      message: `Default for ${field} will be normalized to ${coercion.normalizedType} literal ${coercion.expression}.`,
+      action: "Review the normalized default in the apply report if this value should stay unset.",
+    },
+  ];
 };
 
 const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue>): WorkflowRecommendation[] => {
@@ -60,17 +103,19 @@ const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue
   const typeName = typeof inputs.type === "string" ? inputs.type : null;
   if (!typeName) return [];
 
-  const normalizedType = typeName.toLowerCase() === "enum" ? "enum" : normalizeFieldType(typeName);
-  const constantPath = `*/lib/${module}/${module}.constant.ts`;
-  const dictionaryPath = `*/lib/${module}/${module}.dictionary.ts`;
-  const templatePath = `*/lib/${module}/${capitalize(module)}.Template.tsx`;
+  const policy = addFieldUiPolicyForType(typeName);
+  const normalizedType = policy.normalizedType;
+  const paths = addFieldPaths(inputs);
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  const templateRequested = surfaces?.has("template") ?? false;
+  const includeInLight = inputs.includeInLight === true;
   return [
     ...(normalizedType === "Int" || normalizedType === "Float"
       ? [
           {
             code: "add-field-import",
             kind: "import" as const,
-            target: constantPath,
+            target: paths.constant,
             confidence: "high" as const,
             message: `Import ${normalizedType} from "akanjs/base" before writing field(${normalizedType}).`,
           },
@@ -79,45 +124,147 @@ const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue
     {
       code: "add-field-placement-constant",
       kind: "placement",
-      target: constantPath,
+      target: paths.constant,
       confidence: "high",
       message: `Insert ${field}: field(${normalizedType}) in ${capitalize(module)}Input.`,
     },
     {
       code: "add-field-placement-dictionary",
       kind: "placement",
-      target: dictionaryPath,
+      target: paths.dictionary,
       confidence: "high",
       message: `Add dictionary labels for ${module}.${field}.`,
     },
     {
       code: "add-field-component",
       kind: "ui-component",
-      target: templatePath,
-      confidence: normalizedType === "Int" || normalizedType === "Float" ? "low" : "high",
-      action:
-        normalizedType === "Int" || normalizedType === "Float"
-          ? "Do not auto-edit UI. Check local Template/Unit/View patterns for Field.Text parsing, formatting, validation rules, and dictionary labels before adding a numeric input."
-          : undefined,
-      message:
-        normalizedType === "Int" || normalizedType === "Float"
-          ? `Numeric UI for ${field} (${normalizedType}) requires manual review; a safe numeric input component pattern is not yet detected.`
-          : `Recommended UI component for ${field} (${normalizedType}): ${addFieldComponentForType(typeName)}.`,
+      target: paths.template,
+      confidence: policy.confidence,
+      action: templateRequested
+        ? `apply_workflow will try to add ${policy.component} to Template when the existing Template has a safe generated field-list pattern.`
+        : `Recommended component is ${policy.component}. Pass surfaces=["template"] when this field should be rendered in the Template form.`,
+      message: `Recommended UI component for ${field} (${normalizedType}): ${policy.component}.`,
     },
+    ...(!surfaces
+      ? [
+          {
+            code: "add-field-template-surface-choice",
+            kind: "manual-action" as const,
+            target: paths.template,
+            action: `Choose whether to expose ${field} in Template by passing surfaces=["template"].`,
+            confidence: "medium" as const,
+            message: `Template exposure for ${module}.${field} is not selected yet.`,
+          },
+        ]
+      : []),
+    ...(!includeInLight
+      ? [
+          {
+            code: "add-field-light-projection-choice",
+            kind: "manual-action" as const,
+            target: paths.constant,
+            action: `Pass includeInLight=true when ${field} should appear in Light${capitalize(module)} list/card projections.`,
+            confidence: "medium" as const,
+            message: `Light projection exposure for ${module}.${field} is not selected yet.`,
+          },
+        ]
+      : []),
+    ...(includeInLight
+      ? [
+          {
+            code: "add-field-light-projection",
+            kind: "placement" as const,
+            target: paths.constant,
+            confidence: "high" as const,
+            message: `Add ${field} to Light${capitalize(module)} projection fields.`,
+          },
+        ]
+      : []),
+    ...(surfaces && !templateRequested
+      ? [
+          {
+            code: "add-field-ui-surface-skip",
+            kind: "manual-action" as const,
+            target: paths.template,
+            confidence: "medium" as const,
+            message: `Template is not included in surfaces, so ${module}.${field} will not be auto-rendered there.`,
+          },
+        ]
+      : []),
     {
       code: "add-field-ui-manual-review",
       kind: "manual-action",
-      target: templatePath,
-      action: `Review ${app}:${module} Template/Unit/View/Store surfaces and add ${field} only where the existing pattern is clear. For numeric fields, confirm parser/formatter behavior and validation before using Field.Text.`,
+      target: paths.template,
+      action: `Review ${app}:${module} UI after apply. Template auto-edit requires a generated ${module}Form hook and Layout.Template field list; Unit/View are not auto-edited because list/card placement depends on local layout. Candidate positions: Layout.Template before the closing tag, Light${capitalize(
+        module,
+      )} projection array for list data, and Unit/View card sections for display.`,
       confidence: "medium",
-      message:
-        normalizedType === "Int" || normalizedType === "Float"
-          ? "UI surface edits stay manual because a safe numeric input component pattern is not yet detected."
-          : "UI surface edits are planned as manual-review unless a safe existing field-list pattern is detected.",
+      message: "UI manual review includes the reason auto-edit may be skipped and candidate insertion positions.",
+    },
+    ...createAddFieldDefaultRecommendations(inputs),
+  ];
+};
+
+const createWorkflowPlanPredictedChanges = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): WorkflowPlan["predictedChanges"] => {
+  if (spec.name !== "add-field") return spec.predictedChanges;
+  const paths = addFieldPaths(inputs);
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  const includeInLight = inputs.includeInLight === true;
+  return [
+    {
+      target: paths.constant,
+      action: "modify",
+      applyScope: "auto",
+      reason: includeInLight ? "Field shape and Light projection are added." : "Field shape is added.",
+    },
+    {
+      target: paths.dictionary,
+      action: "modify",
+      applyScope: "auto",
+      reason: "Field label is added.",
+    },
+    ...(!surfaces || surfaces.has("template")
+      ? [
+          {
+            target: paths.template,
+            action: "modify" as const,
+            applyScope: surfaces?.has("template") ? ("auto" as const) : ("manual-review" as const),
+            reason: surfaces?.has("template")
+              ? "Template form is selected for safe-pattern auto insertion."
+              : "Form surface may include the field.",
+          },
+        ]
+      : []),
+    {
+      target: `${addFieldTargetRoot(typeof inputs.app === "string" ? inputs.app : null)}/lib/cnst.ts`,
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated constants may change after sync.",
+    },
+    {
+      target: `${addFieldTargetRoot(typeof inputs.app === "string" ? inputs.app : null)}/lib/dict.ts`,
+      action: "sync",
+      applyScope: "generated-sync",
+      reason: "Generated dictionary barrel may change after sync.",
     },
   ];
 };
 
+const createWorkflowPlanOptionalSurfaces = (
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): Record<string, WorkflowSurfaceMode> => {
+  const optionalSurfaces = spec.optionalSurfaces ?? {};
+  const surfaces = selectedAddFieldSurfaces(inputs);
+  if (spec.name !== "add-field" || !surfaces) return optionalSurfaces;
+  return Object.fromEntries(
+    Object.entries(optionalSurfaces).map(([surface, mode]) => [surface, surfaces.has(surface) ? "include" : mode]),
+  );
+};
+
 const createWorkflowPlanRecommendations = (
   spec: WorkflowSpec,
   inputs: Record<string, WorkflowInputValue>,
@@ -193,15 +340,33 @@ export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string,
       message: `Field type "${fieldType}" is ambiguous in Akan. Use Int for integer fields or Float for decimal fields.`,
     });
   }
+  if (spec.name === "add-field") {
+    const defaultCoercion = addFieldDefaultCoercion(inputs);
+    if (defaultCoercion?.diagnostic) {
+      diagnostics.push({
+        ...defaultCoercion.diagnostic,
+        code: "workflow-default-value-invalid",
+        message: `Plan input default is not valid for ${defaultCoercion.normalizedType}: ${defaultCoercion.diagnostic.message}`,
+      });
+    } else if (defaultCoercion?.normalized && defaultCoercion.expression) {
+      diagnostics.push({
+        severity: "warning",
+        code: "workflow-default-value-normalized",
+        input: "default",
+        failureScope: "source-change",
+        message: `Plan input default will be written as ${defaultCoercion.normalizedType} literal ${defaultCoercion.expression}.`,
+      });
+    }
+  }
 
   return {
     schemaVersion: 1,
     workflow: spec.name,
     mode: "plan",
     inputs,
-    optionalSurfaces: spec.optionalSurfaces ?? {},
+    optionalSurfaces: createWorkflowPlanOptionalSurfaces(spec, inputs),
     steps: spec.steps,
-    predictedChanges: spec.predictedChanges,
+    predictedChanges: createWorkflowPlanPredictedChanges(spec, inputs),
     validation: spec.validation,
     diagnostics,
     recommendations: createWorkflowPlanRecommendations(spec, inputs),

package/workflow/render.ts

@@ -84,19 +84,42 @@ export const renderWorkflowPlan = (plan: WorkflowPlan) =>
     "",
   ].join("\n");
 
-export const renderWorkflowApplyReport = (report: WorkflowApplyReport) =>
-  [
+const renderRecommendation = (recommendation: WorkflowApplyReport["recommendations"][number]) => {
+  const target = recommendation.target ? ` ${recommendation.target}` : "";
+  const action = recommendation.action ? ` Action: ${recommendation.action}` : "";
+  return `- [${recommendation.kind}]${target} ${recommendation.message}${action}`;
+};
+
+const renderDiagnostic = (diagnostic: WorkflowApplyReport["diagnostics"][number]) =>
+  `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`;
+
+export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
+  const manualReviewItems = [
+    ...report.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").map(renderDiagnostic),
+    ...report.recommendations
+      .filter((recommendation) => recommendation.kind === "manual-action")
+      .map(renderRecommendation),
+  ];
+  const validationBlockers = report.diagnostics
+    .filter(
+      (diagnostic) =>
+        diagnostic.severity === "error" &&
+        (diagnostic.failureScope === "workspace-config" || diagnostic.failureScope === "environment"),
+    )
+    .map(renderDiagnostic);
+  return [
     `# Workflow Apply: ${report.workflow}`,
     "",
     `- Mode: ${report.mode}`,
     `- Status: ${report.status}`,
+    ...(report.validationTarget ? [`- Validation target: ${report.validationTarget}`] : []),
     "",
-    "## Changed Files",
+    "## Automatically Modified",
     ...(report.changedFiles.length
       ? report.changedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
       : ["- none"]),
     "",
-    "## Generated Files",
+    "## Generated Sync",
     ...(report.generatedFiles.length
       ? report.generatedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
       : ["- none"]),
@@ -111,15 +134,21 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) =>
       ? report.recommendedValidationCommands.map((command) => `- \`${command.command}\`: ${command.reason}`)
       : ["- none"]),
     "",
+    "## User Review Required",
+    ...(manualReviewItems.length ? manualReviewItems : ["- none"]),
+    "",
+    "## Validation Blockers",
+    ...(validationBlockers.length
+      ? validationBlockers
+      : report.recommendedValidationCommands.length
+        ? ["- none detected during apply; run validation with the validation target for command-level blockers."]
+        : ["- none"]),
+    "",
     "## Diagnostics",
-    ...(report.diagnostics.length
-      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
-      : ["- none"]),
+    ...(report.diagnostics.length ? report.diagnostics.map(renderDiagnostic) : ["- none"]),
     "",
     "## Recommendations",
-    ...(report.recommendations.length
-      ? report.recommendations.map((recommendation) => `- [${recommendation.kind}] ${recommendation.message}`)
-      : ["- none"]),
+    ...(report.recommendations.length ? report.recommendations.map(renderRecommendation) : ["- none"]),
     "",
     "## Next Actions",
     ...(report.nextActions.length
@@ -127,6 +156,7 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) =>
       : ["- none"]),
     "",
   ].join("\n");
+};
 
 export const renderWorkflowApply = (report: WorkflowApplyReport, format: WorkflowFormat = "markdown") =>
   format === "json" ? jsonText(report) : renderWorkflowApplyReport(report);
@@ -141,12 +171,19 @@ export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunR
     `- Workspace status: ${report.workspaceStatus}`,
     `- Overall status: ${report.overallStatus}`,
     "",
+    "## Status Summary",
+    `- Required source-change validation: ${report.summary.sourceChange}`,
+    `- Generated sync validation: ${report.summary.generatedSync}`,
+    `- Workspace configuration validation: ${report.summary.workspaceConfig}`,
+    `- Environment validation: ${report.summary.environment}`,
+    "",
     "## Known Blockers",
     ...(report.knownBlockers.length
       ? report.knownBlockers.map((blocker) => {
           const command = blocker.command ? ` \`${blocker.command}\`` : "";
           const count = blocker.count > 1 ? ` (${blocker.count}x)` : "";
-          return `- [${blocker.failureScope}]${command}${count}: ${blocker.message}`;
+          const known = blocker.known ? " known" : "";
+          return `- [${blocker.failureScope}${known}]${command}${count}: ${blocker.message}`;
         })
       : ["- none"]),
     "",

package/workflow/source.ts

@@ -18,6 +18,26 @@ export const sourceFile = (sys: Sys, path: string, action: PrimitiveChangedFile[
   reason,
 });
 
+export const moduleComponentName = (moduleName: string) =>
+  `${moduleName.slice(0, 1).toUpperCase()}${moduleName.slice(1)}`;
+
+export const moduleSourcePaths = (moduleName: string) => {
+  const componentName = moduleComponentName(moduleName);
+  return {
+    abstract: `lib/${moduleName}/${moduleName}.abstract.md`,
+    constant: `lib/${moduleName}/${moduleName}.constant.ts`,
+    dictionary: `lib/${moduleName}/${moduleName}.dictionary.ts`,
+    service: `lib/${moduleName}/${moduleName}.service.ts`,
+    signal: `lib/${moduleName}/${moduleName}.signal.ts`,
+    store: `lib/${moduleName}/${moduleName}.store.ts`,
+    template: `lib/${moduleName}/${componentName}.Template.tsx`,
+    unit: `lib/${moduleName}/${componentName}.Unit.tsx`,
+    util: `lib/${moduleName}/${componentName}.Util.tsx`,
+    view: `lib/${moduleName}/${componentName}.View.tsx`,
+    zone: `lib/${moduleName}/${componentName}.Zone.tsx`,
+  };
+};
+
 export const generatedFilesForSync = (sys: Sys, reason = "Generated files may change after sync.") =>
   generatedFilePathsForTarget(getSysRoot(sys), reason);
 
@@ -68,6 +88,60 @@ export const titleize = (value: string) =>
 
 export const lowerlize = (value: string) => `${value.slice(0, 1).toLowerCase()}${value.slice(1)}`;
 
+const koLabels: Record<string, string> = {
+  amount: "금액",
+  budget: "예산",
+  category: "카테고리",
+  content: "내용",
+  count: "개수",
+  createdAt: "생성일",
+  date: "날짜",
+  description: "설명",
+  due: "마감일",
+  dueAt: "마감일",
+  email: "이메일",
+  enabled: "활성화",
+  endAt: "종료일",
+  id: "ID",
+  name: "이름",
+  owner: "담당자",
+  priority: "우선순위",
+  project: "프로젝트",
+  rating: "평점",
+  startAt: "시작일",
+  status: "상태",
+  title: "제목",
+  updatedAt: "수정일",
+};
+
+const splitFieldWords = (fieldName: string) =>
+  fieldName
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .split(/\s+/)
+    .map((word) => word.trim())
+    .filter(Boolean);
+
+const koLabelForField = (fieldName: string) => {
+  if (koLabels[fieldName]) return koLabels[fieldName];
+  const words = splitFieldWords(fieldName);
+  const translated = words.map((word) => koLabels[word] ?? koLabels[lowerlize(word)] ?? null);
+  return translated.every(Boolean) ? translated.join(" ") : null;
+};
+
+export const bilingualLabelForField = (fieldName: string) => {
+  const en = titleize(fieldName);
+  return { en, ko: koLabelForField(fieldName) ?? en };
+};
+
+export const bilingualDescriptionForField = (fieldName: string) => {
+  const label = bilingualLabelForField(fieldName);
+  return {
+    en: `Enter ${label.en.toLowerCase()}.`,
+    ko: `${label.ko} 값을 입력합니다.`,
+  };
+};
+
 export const normalizeFieldType = (typeName: string) => {
   const normalizedTypes: Record<string, string> = {
     string: "String",
@@ -96,24 +170,54 @@ export const ensureBaseTypeImport = (content: string, typeName: string) => {
   return `import { ${typeName} } from "akanjs/base";\n${content}`;
 };
 
-const numericDefault = (typeName: "Int" | "Float", rawDefault: string): string | null => {
+export type FieldDefaultValue = string | number | boolean | null;
+
+const numericDefault = (typeName: "Int" | "Float", rawDefault: FieldDefaultValue): string | null => {
+  if (typeof rawDefault === "number") {
+    if (!Number.isFinite(rawDefault)) return null;
+    if (typeName === "Int" && !Number.isInteger(rawDefault)) return null;
+    return String(rawDefault);
+  }
+  if (typeof rawDefault !== "string") return null;
   const trimmed = rawDefault.trim();
   if (!trimmed || !Number.isFinite(Number(trimmed))) return null;
   if (typeName === "Int" && !/^-?\d+$/.test(trimmed)) return null;
   return trimmed;
 };
 
+const booleanDefault = (rawDefault: FieldDefaultValue): string | null => {
+  if (typeof rawDefault === "boolean") return String(rawDefault);
+  if (typeof rawDefault !== "string") return null;
+  const lowered = rawDefault.trim().toLowerCase();
+  return lowered === "true" || lowered === "false" ? lowered : null;
+};
+
+const dateDefault = (rawDefault: FieldDefaultValue): string | null => {
+  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `new Date(${rawDefault})`;
+  if (typeof rawDefault !== "string") return null;
+  const trimmed = rawDefault.trim();
+  if (!trimmed) return null;
+  if (trimmed === "now") return "new Date()";
+  if (!Number.isNaN(Date.parse(trimmed))) return `new Date(${JSON.stringify(trimmed)})`;
+  return null;
+};
+
 export const coerceFieldDefault = (
   typeName: string,
-  defaultValue?: string | null,
-): { expression: string | null; diagnostic?: WorkflowDiagnostic } => {
-  if (defaultValue === undefined || defaultValue === null || defaultValue === "") return { expression: null };
-  const normalizedType = normalizeFieldType(typeName);
+  defaultValue?: FieldDefaultValue,
+  options: { enumValues?: readonly string[] | null } = {},
+): { expression: string | null; diagnostic?: WorkflowDiagnostic; normalized: boolean; normalizedType: string } => {
+  const normalizedType = typeName.toLowerCase() === "enum" ? "enum" : normalizeFieldType(typeName);
+  if (defaultValue === undefined || defaultValue === null || defaultValue === "") {
+    return { expression: null, normalized: false, normalizedType };
+  }
   if (normalizedType === "Int" || normalizedType === "Float") {
     const expression = numericDefault(normalizedType, defaultValue);
-    if (expression !== null) return { expression };
+    if (expression !== null) return { expression, normalized: typeof defaultValue === "string", normalizedType };
     return {
       expression: null,
+      normalized: false,
+      normalizedType,
       diagnostic: {
         severity: "error",
         code: "primitive-default-value-invalid",
@@ -124,10 +228,12 @@ export const coerceFieldDefault = (
     };
   }
   if (normalizedType === "Boolean") {
-    const lowered = defaultValue.trim().toLowerCase();
-    if (lowered === "true" || lowered === "false") return { expression: lowered };
+    const expression = booleanDefault(defaultValue);
+    if (expression !== null) return { expression, normalized: typeof defaultValue === "string", normalizedType };
     return {
       expression: null,
+      normalized: false,
+      normalizedType,
       diagnostic: {
         severity: "error",
         code: "primitive-default-value-invalid",
@@ -137,12 +243,61 @@ export const coerceFieldDefault = (
       },
     };
   }
-  return { expression: JSON.stringify(defaultValue) };
+  if (normalizedType === "Date") {
+    const expression = dateDefault(defaultValue);
+    if (expression !== null) return { expression, normalized: true, normalizedType };
+    return {
+      expression: null,
+      normalized: false,
+      normalizedType,
+      diagnostic: {
+        severity: "error",
+        code: "primitive-default-value-invalid",
+        input: "default",
+        failureScope: "source-change",
+        message: `Default value for Date must be "now", a timestamp, or a parseable date string. Received: ${JSON.stringify(
+          defaultValue,
+        )}.`,
+      },
+    };
+  }
+  if (normalizedType === "enum") {
+    if (typeof defaultValue === "string" && options.enumValues?.includes(defaultValue)) {
+      return { expression: JSON.stringify(defaultValue), normalized: false, normalizedType };
+    }
+    return {
+      expression: null,
+      normalized: false,
+      normalizedType,
+      diagnostic: {
+        severity: "error",
+        code: "primitive-default-value-invalid",
+        input: "default",
+        failureScope: "source-change",
+        message: `Default value for enum must be one of: ${(options.enumValues ?? []).join(", ")}. Received: ${JSON.stringify(
+          defaultValue,
+        )}.`,
+      },
+    };
+  }
+  return {
+    expression: JSON.stringify(String(defaultValue)),
+    normalized: typeof defaultValue !== "string",
+    normalizedType,
+  };
 };
 
-export const fieldExpression = (typeName: string, defaultValue?: string | null) => {
+export const fieldExpression = (
+  typeName: string,
+  defaultValue?: FieldDefaultValue,
+  options: { enumValues?: readonly string[] | null } = {},
+) => {
   const typeExpression = normalizeFieldType(typeName);
-  const defaultExpression = coerceFieldDefault(typeExpression, defaultValue).expression;
+  const defaultExpression = coerceFieldDefault(
+    options.enumValues ? "enum" : typeExpression,
+    defaultValue,
+    options,
+  ).expression;
   const defaultOption = defaultExpression ? `, { default: ${defaultExpression} }` : "";
   return `field(${typeExpression}${defaultOption})`;
 };
@@ -158,6 +313,52 @@ export const insertIntoObject = (content: string, className: string, line: strin
   return `${prefix}${insertion}${suffix}`;
 };
 
+export const insertLightProjectionField = (content: string, moduleClassName: string, fieldName: string) => {
+  const classIndex = content.indexOf(`export class Light${moduleClassName} extends via`);
+  if (classIndex < 0) return null;
+  const arrayMatch = /\[([\s\S]*?)\]\s+as const/.exec(content.slice(classIndex));
+  if (!arrayMatch || arrayMatch.index === undefined) return null;
+  const arrayStart = classIndex + arrayMatch.index;
+  const arrayEnd = arrayStart + arrayMatch[0].length;
+  const fields = [...arrayMatch[1].matchAll(/"([^"]+)"/g)].map((match) => match[1]).filter(Boolean);
+  if (fields.includes(fieldName)) return content;
+  const nextFields = [...fields, fieldName];
+  const nextArray =
+    nextFields.length === 0
+      ? "[] as const"
+      : `[\n${nextFields.map((field) => `  ${JSON.stringify(field)},`).join("\n")}\n] as const`;
+  return `${content.slice(0, arrayStart)}${nextArray}${content.slice(arrayEnd)}`;
+};
+
+export const insertTemplateField = ({
+  content,
+  moduleName,
+  moduleClassName,
+  fieldName,
+  component,
+}: {
+  content: string;
+  moduleName: string;
+  moduleClassName: string;
+  fieldName: string;
+  component: "Field.Text" | "Field.Number" | "Field.Date";
+}) => {
+  if (content.includes(`l("${moduleName}.${fieldName}")`) || content.includes(`.${fieldName}`)) return content;
+  const layoutEndIndex = content.indexOf("    </Layout.Template>");
+  if (layoutEndIndex < 0) return null;
+  const formName = `${moduleName}Form`;
+  if (!content.includes(`const ${formName} = st.use.${moduleName}Form();`)) return null;
+  const fieldSetter = `st.do.set${moduleComponentName(fieldName)}On${moduleClassName}`;
+  const fieldBlock = `      <${component}
+        label={l("${moduleName}.${fieldName}")}
+        desc={l("${moduleName}.${fieldName}.desc")}
+        value={${formName}.${fieldName}}
+        onChange={${fieldSetter}}
+      />
+`;
+  return `${content.slice(0, layoutEndIndex)}${fieldBlock}${content.slice(layoutEndIndex)}`;
+};
+
 export const ensureEnumImport = (content: string) => {
   if (content.includes("enumOf")) return content;
   const baseImport = /import \{ ([^}]+) \} from "akanjs\/base";/.exec(content);
@@ -180,14 +381,15 @@ export const insertEnumClass = (content: string, enumClassName: string, enumName
 
 export const insertDictionaryModelField = (content: string, moduleClassName: string, fieldName: string) => {
   if (new RegExp(`\\b${fieldName}\\s*:`).test(content)) return content;
-  const label = titleize(fieldName);
+  const label = bilingualLabelForField(fieldName);
+  const desc = bilingualDescriptionForField(fieldName);
   const modelIndex = content.indexOf(`.model<${moduleClassName}>((t) => ({`);
   if (modelIndex < 0) return null;
   const objectEndIndex = content.indexOf("  }))", modelIndex);
   if (objectEndIndex < 0) return null;
-  return `${content.slice(0, objectEndIndex)}    ${fieldName}: t([${JSON.stringify(label)}, ${JSON.stringify(
-    label,
-  )}]).desc([${JSON.stringify(label)}, ${JSON.stringify(label)}]),\n${content.slice(objectEndIndex)}`;
+  return `${content.slice(0, objectEndIndex)}    ${fieldName}: t([${JSON.stringify(label.en)}, ${JSON.stringify(
+    label.ko,
+  )}]).desc([${JSON.stringify(desc.en)}, ${JSON.stringify(desc.ko)}]),\n${content.slice(objectEndIndex)}`;
 };
 
 export const ensureConstantTypeImport = (content: string, constantPath: string, typeName: string) => {

package/workflow/types.ts

@@ -1,8 +1,9 @@
 import type { Sys, Workspace } from "../commandDecorators";
+import type { FieldDefaultValue } from "./source";
 
-export type WorkflowInputType = "string" | "string-list" | "surface-mode";
+export type WorkflowInputType = "string" | "string-list" | "surface-mode" | "boolean";
 export type WorkflowSurfaceMode = "infer" | "include" | "skip";
-export type WorkflowInputValue = string | string[] | WorkflowSurfaceMode;
+export type WorkflowInputValue = string | string[] | boolean | WorkflowSurfaceMode;
 export type WorkflowFormat = "markdown" | "json";
 export type WorkflowPlanInputs = Record<string, string | null>;
 export type PrimitiveFormat = "markdown" | "json";
@@ -10,6 +11,12 @@ export type UiSurface = "view" | "unit" | "template";
 export type WorkflowValidationKind = "sync" | "lint" | "typecheck" | "doctor" | "custom";
 export type WorkflowFailureScope = "workspace-config" | "environment" | "source-change" | "unknown";
 export type WorkflowValidationStatus = "passed" | "failed" | "unknown";
+export interface WorkflowValidationSummary {
+  sourceChange: WorkflowValidationStatus;
+  generatedSync: WorkflowValidationStatus;
+  workspaceConfig: WorkflowValidationStatus;
+  environment: WorkflowValidationStatus;
+}
 export type WorkflowOverallStatus = "passed" | "failed" | "blocked-by-workspace-config" | "blocked-by-environment";
 
 export interface PrimitiveTargetInput {
@@ -20,13 +27,17 @@ export interface PrimitiveTargetInput {
 export interface AddFieldInput extends PrimitiveTargetInput {
   field: string | null;
   type: string | null;
-  defaultValue?: string | null;
+  defaultValue?: FieldDefaultValue;
+  surfaces?: string[] | null;
+  includeInLight?: boolean | null;
 }
 
 export interface AddEnumFieldInput extends PrimitiveTargetInput {
   field: string | null;
   values: string | null;
-  defaultValue?: string | null;
+  defaultValue?: FieldDefaultValue;
+  surfaces?: string[] | null;
+  includeInLight?: boolean | null;
 }
 
 export interface WorkflowInputSpec {
@@ -150,6 +161,7 @@ export interface WorkflowKnownBlocker {
   command?: string;
   kind?: WorkflowValidationKind;
   count: number;
+  known?: boolean;
 }
 
 export interface RepairAction {
@@ -222,6 +234,7 @@ export interface WorkflowValidationRunReport {
   status: "passed" | "failed";
   sourceStatus: WorkflowValidationStatus;
   workspaceStatus: WorkflowValidationStatus;
+  summary: WorkflowValidationSummary;
   overallStatus: WorkflowOverallStatus;
   knownBlockers: WorkflowKnownBlocker[];
   commands: WorkflowValidationCommandResult[];

package/workflow/uiPolicy.ts

@@ -0,0 +1,45 @@
+import { normalizeFieldType } from "./source";
+
+export type AddFieldUiComponent = "Field.Text" | "Field.Number" | "Field.Date" | "Field.ToggleSelect";
+
+export const addFieldUiPolicyForType = (typeName: string) => {
+  const normalizedType = typeName.toLowerCase() === "enum" ? "enum" : normalizeFieldType(typeName);
+  if (normalizedType === "Int" || normalizedType === "Float") {
+    return {
+      normalizedType,
+      component: "Field.Number" as const,
+      confidence: "high" as const,
+      autoTemplateSupported: true,
+    };
+  }
+  if (normalizedType === "Date") {
+    return {
+      normalizedType,
+      component: "Field.Date" as const,
+      confidence: "high" as const,
+      autoTemplateSupported: true,
+    };
+  }
+  if (normalizedType === "Boolean" || normalizedType === "enum") {
+    return {
+      normalizedType,
+      component: "Field.ToggleSelect" as const,
+      confidence: "medium" as const,
+      autoTemplateSupported: false,
+    };
+  }
+  if (normalizedType === "String") {
+    return {
+      normalizedType,
+      component: "Field.Text" as const,
+      confidence: "high" as const,
+      autoTemplateSupported: true,
+    };
+  }
+  return {
+    normalizedType,
+    component: "Field.Text" as const,
+    confidence: "low" as const,
+    autoTemplateSupported: false,
+  };
+};