@akanjs/devkit 3.0.0-alpha.45 → 3.0.0-alpha.47

package/akanConfig/akanConfig.test.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { AppExecutor, WorkspaceExecutor } from "../executors";
 import type { PackageJson } from "../types";
 import { AkanAppConfig, AkanLibConfig, deriveDefaultAppId } from "./akanConfig";
 import type { DeepPartial, LibConfigResult } from "./types";
@@ -382,6 +383,52 @@ describe("deriveDefaultAppId", () => {
   });
 });
 
+describe("AkanAppConfig lib externalLibs", () => {
+  test("merges lib-declared external libs into the app's own, deduped", () => {
+    const libAwarePackageJson: PackageJson = {
+      ...packageJson,
+      dependencies: { ...packageJson.dependencies, puppeteer: "24.0.0" },
+    };
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      libAwarePackageJson,
+      { externalLibs: ["@external/runtime"] },
+      baseDevEnv,
+      [],
+      ["@external/runtime", "puppeteer"],
+    );
+
+    expect(config.externalLibs).toEqual(["@external/runtime", "puppeteer"]);
+    expect(config.getProductionPackageJson().dependencies).toMatchObject({
+      "@external/runtime": "2.0.0",
+      puppeteer: "24.0.0",
+    });
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libext-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default { externalLibs: ['shiki'] };\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { externalLibs: ['puppeteer'] };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.externalLibs).toEqual(["shiki", "puppeteer"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;

package/akanConfig/akanConfig.ts

@@ -5,7 +5,7 @@ import type { AkanPlugin } from "akanjs";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
-import { WorkspaceExecutor } from "../executors";
+import { LibExecutor, WorkspaceExecutor } from "../executors";
 import type { BaseDevEnv, PackageJson } from "../types";
 import {
   type AkanMobileConfig,
@@ -195,6 +195,7 @@ export class AkanAppConfig implements AppConfigResult {
     config: DeepPartial<AppConfigResult>,
     baseDevEnv: BaseDevEnv,
     plugins: AkanPlugin[] = [],
+    libExternalLibs: readonly string[] = [],
   ) {
     this.app = app;
     this.rootPackageJson = rootPackageJson;
@@ -203,7 +204,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
     this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
-    this.externalLibs = config?.externalLibs ?? [];
+    this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libExternalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
@@ -412,7 +413,23 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     ]);
     const resolved = typeof configImp === "function" ? configImp(app) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
-    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? []);
+    const libExternalLibs = await AkanAppConfig.#collectLibExternalLibs(app, libs, bustImportCache);
+    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libExternalLibs);
+  }
+  //* Every workspace lib is read, not just this app's lib deps: narrowing the set needs the dependency
+  //* scan, and the incremental page rebundle re-reads this config on every file change.
+  static async #collectLibExternalLibs(app: App, libs: string[], bustImportCache: boolean): Promise<string[]> {
+    const libConfigs = await Promise.all(
+      libs.map(async (libName) =>
+        LibExecutor.from(app, libName)
+          .getConfig({ refresh: bustImportCache })
+          .catch((error: unknown) => {
+            app.logger.warn(`Skipped libs/${libName}/akan.config.ts externalLibs: ${String(error)}`);
+            return null;
+          }),
+      ),
+    );
+    return libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []);
   }
   #resolveProductionDependencyVersion(lib: string) {
     const rootVersion = this.rootPackageJson.dependencies?.[lib] ?? this.rootPackageJson.devDependencies?.[lib];
@@ -529,8 +546,8 @@ export class AkanLibConfig implements LibConfigResult {
     this.externalLibs = config?.externalLibs ?? [];
     this.plugins = plugins;
   }
-  static async from(lib: Lib) {
-    const [configImp] = await Promise.all([import(`${lib.cwdPath}/akan.config.ts`).then((mod) => mod.default)]);
+  static async from(lib: Lib, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
+    const configImp = await AkanAppConfig.importConfigModule(lib.cwdPath, { bustImportCache });
     const resolved = typeof configImp === "function" ? configImp(lib) : configImp;
     const { plugins, ...config } = (resolved ?? {}) as DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
     return new AkanLibConfig(lib, config, plugins ?? []);

package/akanContext.ts

@@ -15,7 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import { isScannedRootEntry, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -666,23 +666,25 @@ export class AkanContextAnalyzer {
       ),
     ];
 
-    for (const app of context.apps) {
-      const appPath = path.join(workspace.workspaceRoot, app.path);
-      for (const entry of await safeReadDir(appPath)) {
-        if (!isScannedAppRootEntry(entry.name)) continue;
-        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sysPath = path.join(workspace.workspaceRoot, sys.path);
+      for (const entry of await safeReadDir(sysPath)) {
+        if (!isScannedRootEntry(sys.type, entry.name)) continue;
+        const allowed = entry.isDirectory()
+          ? rootAllowedDirs[sys.type].has(entry.name)
+          : rootAllowedFiles[sys.type].has(entry.name);
         if (!allowed) {
           const action = repairAction(
             "module-shape",
-            `akan repair module-shape --app ${app.name}`,
-            "Review app root shape and remove or move the unknown entry.",
+            `akan repair module-shape --app ${sys.name}`,
+            `Review ${sys.type} root shape and remove or move the unknown entry.`,
             false,
           );
           diagnostics.push({
             severity: "error",
-            code: "app-root-unknown-entry",
-            path: `${app.path}/${entry.name}`,
-            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in app root: ${app.path}/${entry.name}`,
+            code: `${sys.type}-root-unknown-entry`,
+            path: `${sys.path}/${entry.name}`,
+            message: `Unexpected ${entry.isDirectory() ? "folder" : "file"} in ${sys.type} root: ${sys.path}/${entry.name}`,
             repairActions: [action],
           });
           repairActions.push(action);

package/executors.ts

@@ -23,6 +23,7 @@ import { pathToFileURL } from "node:url";
 import type { AkanPlugin, AkanSyncContext, PluginRuntimeContext } from "akanjs";
 import {
   capitalize,
+  getPageSourceFileViolation,
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
@@ -1006,6 +1007,16 @@ export class SysExecutor extends Executor {
     const path = this.type === "app" ? `apps/${this.name}/lib` : `libs/${this.name}/lib`;
     return await this.workspace.getDirInModule(path, this.name);
   }
+  async getPageConventionViolations(): Promise<{ relativePath: string; reason: string }[]> {
+    if (!(await this.exists("page"))) return [];
+    const violations: { relativePath: string; reason: string }[] = [];
+    for (const entry of await this.getAllFiles("**/*", { cwd: this.getPath("page") })) {
+      const relativePath = entry.split(path.sep).join("/");
+      const reason = getPageSourceFileViolation(relativePath);
+      if (reason) violations.push({ relativePath: `page/${relativePath}`, reason });
+    }
+    return violations;
+  }
 
   #scanInfo: AppInfo | LibInfo | null = null;
   hasScanInfo() {
@@ -1707,7 +1718,7 @@ export class LibExecutor extends SysExecutor {
   #akanConfig: AkanLibConfig | null = null;
   override async getConfig({ refresh }: { refresh?: boolean } = {}) {
     if (this.#akanConfig && !refresh) return this.#akanConfig;
-    this.#akanConfig = await AkanLibConfig.from(this);
+    this.#akanConfig = await AkanLibConfig.from(this, { bustImportCache: refresh });
     return this.#akanConfig;
   }
 }

package/frontendBuild/styleGuard.test.ts

@@ -67,6 +67,21 @@ describe("StyleGuard daisyui-legacy", () => {
   test("does not flag bare ambiguous names that collide with Tailwind", () => {
     expect(scan('<div className="card input badge btn" />')).toHaveLength(0);
   });
+
+  test("flags daisyUI colour slots the vocabulary dropped", () => {
+    expect(rules('<div className="bg-base-100" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<div className="text-base-content/70" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<div className="border-t-base-300" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<div className="text-primary-content" />')).toEqual(["daisyui-legacy"]);
+    expect(rules('<div className="border-error/30 bg-error/5" />')).toEqual(["daisyui-legacy", "daisyui-legacy"]);
+  });
+
+  test("does not flag colour slots that survived into the semantic vocabulary", () => {
+    expect(scan('<div className="bg-primary text-primary-foreground" />')).toHaveLength(0);
+    expect(scan('<div className="bg-neutral text-info border-warning" />')).toHaveLength(0);
+    expect(scan('<div className="bg-destructive/10 text-destructive" />')).toHaveLength(0);
+    expect(scan('<div className="content-center justify-content" />')).toHaveLength(0);
+  });
 });
 
 // The fixtures below must contain a literal `${`. Writing it inside a plain string trips biome's

package/frontendBuild/styleGuard.ts

@@ -90,6 +90,13 @@ const DAISYUI_LEGACY_RE = new RegExp(
   "g",
 );
 
+// daisyUI 색 슬롯. 어휘 폐쇄가 이 이름들을 지웠으므로 CSS 가 생성되지 않는다 — 컴포넌트 클래스와 같은
+// 무증상 실패다. 시맨틱 어휘에 살아남은 슬롯(primary·secondary·accent·neutral·info·success·warning)은
+// 정상이므로 제외하고, 사라진 것(base-*, *-content, error)만 잡는다.
+const DAISYUI_TOKEN =
+  "(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)";
+const DAISYUI_TOKEN_RE = new RegExp(`${LEAD}(?:${PREFIX})-${DAISYUI_TOKEN}${TAIL}`, "g");
+
 const ALL_RULES: StyleGuardRule[] = [
   "raw-palette",
   "arbitrary-color",
@@ -247,6 +254,16 @@ export class StyleGuard {
         }),
       );
     }
+    for (const m of scan.matchAll(DAISYUI_TOKEN_RE)) {
+      out.push(
+        this.#violation(file, m.index ?? 0, {
+          rule: "daisyui-legacy",
+          severity: "error",
+          suggestion:
+            "daisyUI 색 슬롯은 어휘에서 제거됐습니다 — base-100/200/300→background/muted/border, base-content→foreground, *-content→*-foreground, error→destructive.",
+        }),
+      );
+    }
     for (const m of scan.matchAll(INTERPOLATED_ARBITRARY_RE)) {
       out.push(
         this.#violation(file, m.index ?? 0, {

package/lint/no-daisyui-legacy-class.grit

@@ -2,19 +2,36 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // daisyUI was removed from the UI system; its component classes (`btn-primary`, `card-body`,
-// `mockup-code`, ...) no longer have any CSS behind them and silently render unstyled. Grit
-// port of styleGuard's `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// `mockup-code`, ...) and its colour slots (`bg-base-100`, `text-base-content`, `bg-error`)
+// no longer have any CSS behind them and silently render unstyled. Grit port of styleGuard's
+// `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
 // Only high-signal compound names are matched; bare ambiguous words that collide with
-// Tailwind or app classes (`card`, `input`, `badge`, `btn`) are deliberately not flagged.
+// Tailwind or app classes (`card`, `input`, `badge`, `btn`, `divider`) are deliberately not
+// flagged, and colour slots that survived into the semantic vocabulary (`primary`, `info`,
+// `success`, `warning`, `neutral`) are not either — only the slots the vocabulary dropped.
+// Biome keeps only the first diagnostic a single plugin registers on a node, so a string
+// carrying both halves reports the component one and surfaces the colour one on the next run.
 or {
   JsxString() as $s,
   JsStringLiteralExpression() as $s,
   JsTemplateChunkElement() as $s
 } where {
-  $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
-  register_diagnostic(
-    span = $s,
-    message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
-    severity = "error"
-  )
+  any {
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        severity = "error"
+      )
+    },
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
+        severity = "error"
+      )
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.45",
+  "version": "3.0.0-alpha.47",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.45",
+    "akanjs": "3.0.0-alpha.47",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/qualityScanner.test.ts

@@ -205,4 +205,47 @@ describe("AkanQualityScanner layout rules", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
   });
+
+  test("flags an unknown lib root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/client.ts": "export const client = 1;\n",
+      "libs/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/helper.ts");
+  });
+
+  test("flags a root folder no facet owns, on both sides", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/base/helper.ts": "export const helper = 1;\n",
+      "apps/demo/common/helper.ts": "export const helper = 1;\n",
+      "libs/demo/base/helper.ts": "export const helper = 1;\n",
+      "libs/demo/common/helper.ts": "export const helper = 1;\n",
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+
+    expect(rulesOf(result, "akan.layout.app-root-folder").map((warning) => warning.file)).toEqual([
+      "apps/demo/base/helper.ts",
+    ]);
+    expect(rulesOf(result, "akan.layout.lib-root-folder").map((warning) => warning.file)).toEqual([
+      "libs/demo/base/helper.ts",
+    ]);
+  });
+
+  test("keeps a root signal test out of the lib facet rule", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/lib/cnst.ts": "export const cnst = 1;\n",
+      "libs/demo/lib/user.signal.test.ts": "export const test = 1;\n",
+      "libs/demo/lib/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-facet-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/lib/helper.ts");
+  });
 });

package/qualityScanner.ts

@@ -7,7 +7,7 @@ import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
 import { FormSetterScanner } from "./formSetterScanner";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
@@ -90,7 +90,7 @@ const SUGGESTED_RULES = [
   "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
   "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
   "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
-  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Move shared app and lib utilities to common/ instead of creating apps/*/base or libs/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
@@ -132,8 +132,14 @@ const RULE_FIXES: Record<string, string> = {
     "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix — only PascalCase components and their `<Component>Props` interface belong here.",
   "akan.layout.app-root-file":
     "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.app-root-folder":
+    "Move the folder's contents into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-root-file":
-    "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+    "Move the file into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-folder":
+    "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-facet-file":
+    "Move the file into a domain module folder under lib/; keep the lib facet root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
   "akan.ssr.unnecessary-use-client":
@@ -413,26 +419,31 @@ export class AkanQualityScanner {
   }
 
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
-    const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
-      warnings.push({
-        rule: "akan.layout.app-root-file",
-        scope: "layout",
-        severity: "warning",
-        file: sourceFile.file,
-        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`,
-      });
+    const rootEntry = getSysRootEntry(sourceFile.file);
+    if (rootEntry) {
+      const { type, name, isDir } = rootEntry;
+      const allowed = isDir ? rootAllowedDirs[type].has(name) : rootAllowedFiles[type].has(name);
+      const kind = isDir ? "folder" : "file";
+      if (!allowed) {
+        warnings.push({
+          rule: `akan.layout.${type}-root-${kind}`,
+          scope: "layout",
+          severity: "warning",
+          file: sourceFile.file,
+          message: `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`,
+        });
+      }
     }
 
-    const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
+    const libFacetFile = getLibFacetRootFile(sourceFile.file);
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
       warnings.push({
-        rule: "akan.layout.lib-root-file",
+        rule: "akan.layout.lib-facet-file",
         scope: "layout",
         severity: "warning",
         file: sourceFile.file,
-        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`,
+        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`,
       });
     }
 
@@ -826,7 +837,19 @@ function getConventionDescription(suffix: (typeof CONVENTION_SUFFIXES)[number],
   return `${modelName}Store`;
 }
 
-function getLibRootFile(file: string) {
+const sysRootTypes = { apps: "app", libs: "lib" } as const;
+
+function getSysRootEntry(file: string) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3) return null;
+  const type = sysRootTypes[root as keyof typeof sysRootTypes];
+  if (!type) return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+
+function getLibFacetRootFile(file: string) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];

package/scanInfo.ts

@@ -9,9 +9,8 @@ import type {
   PkgScanResult,
   ScanResult,
 } from "./akanConfig";
-
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
-import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -57,7 +56,6 @@ const moduleUiFileTypes = {
   scalar: new Set(["Template", "Unit"]),
 } satisfies Record<ModuleKind, Set<string>>;
 const testFilePattern = /\.(test|spec)\.(ts|tsx)$/;
-const rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
 
 // The dependency scanner needs `typescript` (~65MB resident). Only the scan/sync commands run it, so
 // load it on demand rather than through the module graph of every process that imports scan info.
@@ -65,8 +63,6 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
   (await import("./dependencyScanner")).TypeScriptDependencyScanner.from(exec);
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
-const isAllowedLibRootFile = (filename: string) =>
-  libFacetRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
 async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {
@@ -85,24 +81,29 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);
   };
 
-  if (exec.type === "app") {
-    const { files, dirs } = await exec.getFilesAndDirs(".");
-    files
-      .filter((filename) => !appRootAllowedFiles.has(filename))
-      .forEach((filename) => {
-        addViolation(filename, "unsupported app root file");
-      });
-    dirs
-      .filter((dirname) => !appRootAllowedDirs.has(dirname))
-      .forEach((dirname) => {
-        addViolation(dirname, "unsupported app root folder");
-      });
-  }
+  const allowedRootFiles: ReadonlySet<string> = rootAllowedFiles[exec.type];
+  const allowedRootDirs: ReadonlySet<string> = rootAllowedDirs[exec.type];
+  const { files, dirs } = await exec.getFilesAndDirs(".");
+  files
+    .filter((filename) => !allowedRootFiles.has(filename))
+    .forEach((filename) => {
+      addViolation(filename, `unsupported ${exec.type} root file`);
+    });
+  dirs
+    .filter((dirname) => !allowedRootDirs.has(dirname))
+    .forEach((dirname) => {
+      addViolation(dirname, `unsupported ${exec.type} root folder`);
+    });
+
+  //* An app validates its page tree in `getPageKeys`, which a lib has no equivalent of — so a lib's own
+  //* routes went unchecked until whichever app opted into them with `syncPageLibs` blew up on the sync.
+  if (exec.type === "lib")
+    for (const { relativePath, reason } of await exec.getPageConventionViolations()) addViolation(relativePath, reason);
 
   libRoot.files
-    .filter((filename) => !isAllowedLibRootFile(filename))
+    .filter((filename) => !isAllowedLibFacetRootFile(filename))
     .forEach((filename) => {
-      addViolation(path.join("lib", filename), "unsupported lib root file");
+      addViolation(path.join("lib", filename), "unsupported lib facet root file");
     });
 
   libRoot.dirs

package/workspaceLayout.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import {
+  appRootAllowedDirs,
+  appRootAllowedFiles,
+  isAllowedLibFacetRootFile,
+  isScannedRootEntry,
+  libRootAllowedDirs,
+  libRootAllowedFiles,
+} from "./workspaceLayout";
 
 describe("app root layout allowlist", () => {
   test("admits the scoped agent guides sync writes into every app", () => {
@@ -19,8 +26,53 @@ describe("app root layout allowlist", () => {
   });
 
   test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
-    expect(isScannedAppRootEntry(".DS_Store")).toBe(false);
-    expect(isScannedAppRootEntry(".akan")).toBe(true);
-    expect(isScannedAppRootEntry("lib")).toBe(true);
+    expect(isScannedRootEntry("app", ".DS_Store")).toBe(false);
+    expect(isScannedRootEntry("app", ".akan")).toBe(true);
+    expect(isScannedRootEntry("app", "lib")).toBe(true);
+  });
+});
+
+describe("lib root layout allowlist", () => {
+  test("admits what the libRoot template and scan write", () => {
+    for (const filename of ["AGENTS.md", "akan.config.ts", "akan.lib.json", "client.ts", "index.ts", "server.ts"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(true);
+    }
+    for (const dirname of ["common", "env", "lib", "page", "plugin", "private", "public", "srvkit", "ui", "webkit"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(true);
+    }
+  });
+
+  test("rejects a lib root entry no facet owns", () => {
+    expect(libRootAllowedFiles.has("helper.ts")).toBe(false);
+    expect(libRootAllowedDirs.has("base")).toBe(false);
+  });
+
+  test("rejects the app-only run and mobile entries", () => {
+    for (const filename of ["main.ts", "capacitor.config.ts", "akan.app.json"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(false);
+    }
+    for (const dirname of [".akan", "android", "ios", "mobile", "script", "secrets"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(false);
+    }
+  });
+
+  test("skips dotfile artifacts in a lib root too", () => {
+    expect(isScannedRootEntry("lib", ".gitignore")).toBe(false);
+    expect(isScannedRootEntry("lib", ".akan")).toBe(false);
+    expect(isScannedRootEntry("lib", "ui")).toBe(true);
+  });
+});
+
+describe("lib facet root allowlist", () => {
+  test("admits the generated support facets and a root signal test", () => {
+    expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("option.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.test.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.spec.ts")).toBe(true);
+  });
+
+  test("rejects a hand-written file beside the barrels", () => {
+    expect(isAllowedLibFacetRootFile("helper.ts")).toBe(false);
+    expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
 });

package/workspaceLayout.ts

@@ -7,6 +7,8 @@
  * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
  */
 
+export type SysType = "app" | "lib";
+
 export const appRootAllowedFiles = new Set([
   // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
   "AGENTS.md",
@@ -41,6 +43,43 @@ export const appRootAllowedDirs = new Set([
   "webkit",
 ]);
 
+/**
+ * 라이브러리 루트는 앱 루트에서 실행/모바일 전용 항목(`main.ts`, `capacitor.config.ts`, `.akan`,
+ * `android`, `ios`, `mobile`, `script`, `secrets`)을 뺀 집합이다 — 라이브러리는 부팅되지도, 패키징되지도
+ * 않는다. `index.ts` 는 lib 에만 생성되고, `README.md` / `tsconfig.spec.json` 은 라이브러리가 패키지로
+ * 배포되기 때문에 남는다. `public` / `private` 은 syncAssets 가 앱으로 심링크하므로 라이브러리도 가진다.
+ */
+export const libRootAllowedFiles = new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "README.md",
+  "akan.config.ts",
+  "akan.lib.json",
+  "client.ts",
+  "index.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+  "tsconfig.spec.json",
+  "tsconfig.tsbuildinfo",
+]);
+
+export const libRootAllowedDirs = new Set([
+  "common",
+  "env",
+  "lib",
+  "page",
+  "plugin",
+  "private",
+  "public",
+  "srvkit",
+  "ui",
+  "webkit",
+]);
+
+export const rootAllowedFiles = { app: appRootAllowedFiles, lib: libRootAllowedFiles } as const;
+export const rootAllowedDirs = { app: appRootAllowedDirs, lib: libRootAllowedDirs } as const;
+
 export const libFacetRootAllowedFiles = new Set([
   "cnst.ts",
   "db.ts",
@@ -53,8 +92,15 @@ export const libFacetRootAllowedFiles = new Set([
   "useServer.ts",
 ]);
 
+/** `<model>.signal.test.ts` — lib 파싯 루트에 놓이는 유일한 비생성 파일 (테스트가 배럴 전체를 부팅한다). */
+const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
+
+export const isAllowedLibFacetRootFile = (filename: string) =>
+  libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
+
 /**
- * scanSync 는 앱 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
+ * scanSync 는 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
  * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
  */
-export const isScannedAppRootEntry = (name: string) => !name.startsWith(".") || appRootAllowedDirs.has(name);
+export const isScannedRootEntry = (type: SysType, name: string) =>
+  !name.startsWith(".") || rootAllowedDirs[type].has(name);