@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/skills/erp-kit-module-4-plan-review/SKILL.md

@@ -57,11 +57,25 @@ After ALL agents return:
 3. Merge all `inconsistencies[]` arrays into a single list
 4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
 5. Calculate totals across all summaries
-6. Render the final report below
 
-## Report Format
+## Step 4: Severity Validation
 
-Render the aggregated results as markdown:
+Subagents tend to over-classify. Before rendering the report, re-evaluate every non-pass finding:
+
+- **"Is this a real gap or a design choice?"** — If the feature intentionally omits a command/query/model (e.g., handled by another module, deferred to a later phase, or covered by a generic mechanism), drop it from the report
+- **"Does the feature doc explicitly require this?"** — Only flag gaps for capabilities the feature doc actually specifies. Do not invent requirements the feature does not mention
+- **"Does this block implementation?"** → `critical`
+- **"Will this cause rework during implementation?"** → `major`
+- All no → `nit`, regardless of subagent label
+
+## Step 5: Determine Verdict
+
+- **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+- **NEEDS CHANGES**: one or more `critical` or `major` findings
+
+## Step 6: Render Report
+
+Render the aggregated results as markdown (after severity validation):
 
 ### Feature Parity Review Report
 
@@ -146,11 +160,20 @@ Render the aggregated results as markdown:
 
 ### 8. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
+
+1. `critical` — missing required docs, fundamental parity gaps (must fix)
+2. `major` — missing business rules, incomplete error scenarios (should fix)
+3. `nit` — minor naming inconsistencies, optional improvements (informational only)
+
+### 9. Verdict
+
+**Verdict: APPROVED / NEEDS CHANGES**
+
+- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
+- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."
 
-1. Create missing docs (highest priority)
-2. Add missing business rules / error scenarios
-3. Resolve inconsistencies
+Severity counts: `critical: N, major: N, nit: N`
 
 ## References
 

package/skills/erp-kit-module-4-plan-review/references/parity-report-format.md

@@ -50,3 +50,18 @@ Cross-cutting issues found during the check that don't fit a single gap entry (e
 ### summary
 
 Aggregate counts. `total_checks = passed + failed + skipped`.
+
+## Router-Level Severity and Verdict
+
+The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.
+
+The router classifies each finding as:
+
+- `critical`: blocks progress — missing required doc, fundamental design mismatch
+- `major`: should fix — incomplete coverage, unclear mapping, missing business rules
+- `nit`: nice to have — minor naming inconsistency, optional doc improvement, cosmetic issue
+
+Verdict rule:
+
+- `APPROVED`: zero `critical` and zero `major` findings (nits only, or all pass)
+- `NEEDS_CHANGES`: one or more `critical` or `major` findings

package/skills/erp-kit-module-6-impl-review/SKILL.md

@@ -59,7 +59,14 @@ After ALL agents return:
 3. Merge all `inconsistencies[]` arrays into a single list
 4. Deduplicate: if two gaps share the same `source + target + check`, keep only one
 5. Calculate totals across all summaries
-6. Render the final report below
+6. **Classify severity** — for each non-pass gap and inconsistency, the router assigns a severity based on the finding's `check`, `status`, and `detail`:
+   - `critical`: missing implementation of documented feature, broken doc-code contract — blocks progress
+   - `major`: incomplete implementation, missing test case for documented business rule — should fix
+   - `nit`: minor naming difference, optional JSDoc, cosmetic issue — does NOT block the review
+7. **Determine verdict**:
+   - **APPROVED**: zero `critical` and zero `major` findings (nits only, or all pass)
+   - **NEEDS CHANGES**: one or more `critical` or `major` findings
+8. Render the final report below
 
 ## Report Format
 
@@ -171,13 +178,20 @@ Render the aggregated results as markdown:
 
 ### 10. Recommendations
 
-Numbered list of actionable fixes, grouped by priority:
+Numbered list of actionable fixes, grouped by severity:
 
-1. Add missing model fields/states (highest priority)
-2. Implement missing business rules
-3. Define missing error classes (re-run `erp-kit module generate code -p <path>`)
-4. Add missing test cases
-5. Fix inconsistencies
+1. `critical` — missing model fields/states, broken doc-code contract (must fix)
+2. `major` — missing business rules, incomplete test coverage (should fix)
+3. `nit` — minor naming differences, optional JSDoc, cosmetic issues (informational only)
+
+### 11. Verdict
+
+**Verdict: APPROVED / NEEDS CHANGES**
+
+- If APPROVED with nits: "Review passed. The following nits are informational and do not block progress:" followed by the nit list.
+- If NEEDS CHANGES: "Review requires changes. Fix all critical and major issues, then re-run the review."
+
+Severity counts: `critical: N, major: N, nit: N`
 
 ## References
 

package/skills/erp-kit-module-6-impl-review/references/impl-parity-report-format.md

@@ -50,3 +50,18 @@ Cross-cutting issues found during the check that don't fit a single gap entry (e
 ### summary
 
 Aggregate counts. `total_checks = passed + failed + skipped`.
+
+## Router-Level Severity and Verdict
+
+The router (SKILL.md Step 3) assigns severity to each non-pass finding after collecting all agent results. Agents do NOT assign severity — they only report `status` and `detail`.
+
+The router classifies each finding as:
+
+- `critical`: blocks progress — missing implementation of documented feature, broken contract between doc and code
+- `major`: should fix — incomplete implementation, missing test case for documented business rule
+- `nit`: nice to have — minor naming difference, optional JSDoc improvement, cosmetic code style issue
+
+Verdict rule:
+
+- `APPROVED`: zero `critical` and zero `major` findings (nits only, or all pass)
+- `NEEDS_CHANGES`: one or more `critical` or `major` findings

package/skills/erp-kit-module-shared/SKILL.md

@@ -7,6 +7,10 @@ description: Shared references for erp-kit module skills. Not invoked directly
 
 Canonical reference files shared across module skills. Individual skills reference these instead of maintaining their own copies.
 
+## Design Philosophy
+
+Modules are intentionally simple. Each module is a thin layer of domain logic over the database — avoid introducing unnecessary abstractions, deep inheritance hierarchies, or complex patterns. Over-engineering is actively harmful: it makes modules harder to understand, test, and maintain. When in doubt, choose the straightforward approach. A few lines of duplicated code is better than a premature abstraction.
+
 ## References
 
 - [Module structure](references/structure.md)

package/skills/erp-kit-module-shared/references/commands.md

@@ -177,7 +177,7 @@ const units = await db
 
 ## Implementation Considerations
 
-- **Error handling**: Use `ok()` / `err()` from `shared` — do not throw
+- **Error handling**: Use `ok()` / `err()` from `@tailor-platform/erp-kit/module` — do not throw
 - **Validation**: Check referenced entities exist before operating, return `err()` if not found
 
 ## Conventions

package/skills/erp-kit-module-shared/references/queries.md

@@ -8,8 +8,8 @@ Run `erp-kit module generate code -p <path>` to generate query shells from `docs
 
 ```typescript
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getItem";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getItem = defineQuery(run);
 ```
@@ -17,9 +17,8 @@ export const getItem = defineQuery(run);
 ### Hand-written implementation
 
 ```typescript
-import type { ReadonlyDB } from "../../../shared";
-import { ok } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetItemInput = { id: string } | { sku: string };
 
@@ -45,7 +44,7 @@ For queries beyond simple lookups (joins, aggregations, complex filters), write
 
 - `defineQuery` wraps all queries via generated shells
 - `ReadonlyDB<DB>` ensures read-only access
-- All queries return Result types using `ok()` / `err()` from `shared` — consistent with commands
+- All queries return Result types using `ok()` / `err()` from `@tailor-platform/erp-kit/module` — consistent with commands
 - Get queries return `ok({ entity: T | null })` using `executeTakeFirst()`
 - List queries return `ok(PaginatedResult<T>)` using pagination utilities — see [Paginated List Queries](#paginated-list-queries)
 - Input types: `type` for union inputs (get), `interface` for single-shape inputs (list)
@@ -81,14 +80,14 @@ interface PaginatedResult<T> {
 3. Use `buildPaginatedResult(rows, limit)` to build the response — the limit+1 strategy determines `hasNextPage` without a separate count query
 
 ```typescript
+import type { DB } from "../generated/kysely-tailordb";
 import {
   ok,
   type ReadonlyDB,
   type PaginationInput,
   buildPaginatedResult,
   DEFAULT_PAGE_SIZE,
-} from "../../../shared";
-import type { DB } from "../generated/kysely-tailordb";
+} from "@tailor-platform/erp-kit/module";
 
 // Define sortable fields for this query
 type UnitOrderByField = "name" | "symbol" | "createdAt";

package/src/commands/app/index.ts

@@ -4,8 +4,9 @@ import { defineCommand, arg } from "politty";
 import { runCheck } from "../check";
 import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
 import { runGenerateDoc, APP_DOC_TYPES, type DocType } from "../generate-doc";
-import { runGenerateAppCode } from "../../generator/generate-code";
+import { runGenerateAppCode } from "../../generator/generate-app-code";
 import { runInitAppWithReadme } from "../init-module";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
 
 const cwd = process.cwd();
 
@@ -20,9 +21,11 @@ const checkCommand = defineCommand({
   name: "check",
   description: "Validate app docs against schemas",
   args: pathArgs,
-  run: async (args) => {
-    const exitCode = await runCheck({ appRoot: args.path }, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runCheck({ appRoot: args.path }, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -30,10 +33,12 @@ const syncCheckCommand = defineCommand({
   name: "sync-check",
   description: "Validate source <-> doc correspondence",
   args: pathArgs,
-  run: async (args) => {
-    const result = await runSyncCheck({ appRoot: args.path }, cwd);
-    console.log(formatSyncCheckReport(result));
-    process.exit(result.exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const result = await runSyncCheck({ appRoot: args.path }, cwd);
+      console.log(formatSyncCheckReport(result));
+      return result.exitCode === 0 ? success() : silentFailure(result.exitCode);
+    });
   },
 });
 
@@ -50,9 +55,11 @@ const initCommand = defineCommand({
       description: "Parent directory where the app will be created",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -69,9 +76,11 @@ const docCommand = defineCommand({
       description: "Item name (required for most types)",
     }),
   }),
-  run: async (args) => {
-    const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
-    process.exit(exitCode);
+  run: (args) => {
+    return executeCommand(async () => {
+      const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -80,9 +89,11 @@ const codeCommand = defineCommand({
   description: "Generate boilerplate source files from docs",
   args: pathArgs,
   run: (args) => {
-    const appPath = path.resolve(cwd, args.path);
-    const exitCode = runGenerateAppCode(appPath);
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const appPath = path.resolve(cwd, args.path);
+      const exitCode = runGenerateAppCode(appPath);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 

package/src/commands/check.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { buildCheckTargets } from "./check";
+import { buildCheckTargets } from "./lib/discovery";
 
 describe("buildCheckTargets", () => {
   it("generates module targets when modulesRoot is set", () => {

package/src/commands/check.ts

@@ -1,41 +1,8 @@
 import { runMdschema } from "../mdschema";
 import { ALL_SCHEMAS } from "../schemas";
-export interface CheckTarget {
-  glob: string;
-  schemaKey: string;
-}
-
-export function buildCheckTargets(config: {
-  modulesRoot?: string;
-  appRoot?: string;
-}): CheckTarget[] {
-  const targets: CheckTarget[] = [];
-
-  if (config.modulesRoot) {
-    const m = config.modulesRoot;
-    targets.push(
-      { glob: `${m}/[a-zA-Z]*/docs/features/*.md`, schemaKey: "feature" },
-      { glob: `${m}/[a-zA-Z]*/docs/commands/*.md`, schemaKey: "command" },
-      { glob: `${m}/[a-zA-Z]*/docs/models/*.md`, schemaKey: "model" },
-      { glob: `${m}/[a-zA-Z]*/docs/queries/*.md`, schemaKey: "query" },
-      { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
-    );
-  }
+import { buildCheckTargets } from "./lib/discovery";
 
-  if (config.appRoot) {
-    const a = config.appRoot;
-    targets.push(
-      { glob: `${a}/[a-zA-Z]*/README.md`, schemaKey: "app" },
-      { glob: `${a}/[a-zA-Z]*/docs/actors/*.md`, schemaKey: "actors" },
-      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/README.md`, schemaKey: "business-flow" },
-      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/story/*.md`, schemaKey: "story" },
-      { glob: `${a}/[a-zA-Z]*/docs/screen/*.md`, schemaKey: "screen" },
-      { glob: `${a}/[a-zA-Z]*/docs/resolver/*.md`, schemaKey: "resolver" },
-    );
-  }
-
-  return targets;
-}
+export type { CheckTarget } from "./lib/discovery";
 
 export async function runCheck(
   config: { modulesRoot?: string; appRoot?: string },

package/src/commands/doc/index.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { executeCommand, success, silentFailure } from "../lib/command-result";
+import { runDocModules } from "./modules";
+import { runDocModule } from "./module";
+import { runDocSearch } from "./search";
+
+const formatArg = arg(z.enum(["text", "json"]).default("text"), {
+  alias: "f",
+  description: "Output format (text or json)",
+});
+
+const modulesCommand = defineCommand({
+  name: "modules",
+  description: "List all modules with capabilities overview",
+  args: z.object({
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocModules(args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+const moduleCommand = defineCommand({
+  name: "module",
+  description: "Show documentation for a specific module",
+  args: z.object({
+    name: arg(z.string(), {
+      positional: true,
+      description: "Module name",
+    }),
+    type: arg(z.string().optional(), {
+      positional: true,
+      description: "Doc type (command, query, model, feature)",
+    }),
+    docName: arg(z.string().optional(), {
+      positional: true,
+      description: "Doc name",
+    }),
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocModule(args.name, args.type, args.docName, args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+const searchCommand = defineCommand({
+  name: "search",
+  description: "Search across all module documentation",
+  args: z.object({
+    query: arg(z.string(), {
+      positional: true,
+      description: "Search query",
+    }),
+    type: arg(z.string().optional(), {
+      alias: "t",
+      description: "Filter by doc type (command, query, model, feature, readme)",
+    }),
+    format: formatArg,
+  }),
+  run: (args) => {
+    return executeCommand(() => {
+      const exitCode = runDocSearch(args.query, args.type, args.format);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
+  },
+});
+
+export const docCommand = defineCommand({
+  name: "doc",
+  description: "Browse module documentation",
+  subCommands: {
+    modules: modulesCommand,
+    module: moduleCommand,
+    search: searchCommand,
+  },
+});

package/src/commands/doc/module.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { runDocModule } from "./module";
+
+describe("runDocModule", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("outputs README and available docs for a known module", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization");
+    expect(exitCode).toBe(0);
+
+    const output = logs.join("\n");
+    expect(output).toContain("## Overview");
+    expect(output).toContain("## Available Documentation");
+    expect(output).toContain("CreateCompany");
+    expect(output).toContain("GetCompany");
+    expect(output).toContain("Company");
+  });
+
+  it("outputs raw doc content for a specific command", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization", "command", "CreateCompany");
+    expect(exitCode).toBe(0);
+
+    const output = logs.join("\n");
+    expect(output).toContain("# CreateCompany");
+    expect(output).toContain("## Overview");
+    expect(output).toContain("## Business Rules");
+    expect(output).toContain("## Error Scenarios");
+  });
+
+  it("returns error for unknown module", () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("nonexistent");
+    expect(exitCode).toBe(1);
+
+    const output = errors.join("\n");
+    expect(output).toContain("Module not found: nonexistent");
+    expect(output).toContain("Available modules:");
+  });
+
+  it("returns error for unknown doc type", () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization", "invalid", "Foo");
+    expect(exitCode).toBe(1);
+
+    const output = errors.join("\n");
+    expect(output).toContain("Unknown doc type: invalid");
+    expect(output).toContain("Available types:");
+  });
+
+  it("outputs valid JSON for module detail with --format json", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization", undefined, undefined, "json");
+    expect(exitCode).toBe(0);
+
+    const parsed = JSON.parse(logs.join("\n")) as Record<string, unknown>;
+    expect(parsed).toHaveProperty("module", "organization");
+    expect(parsed).toHaveProperty("readme");
+    expect(parsed).toHaveProperty("docs");
+    expect(typeof parsed.readme).toBe("string");
+    const docs = parsed.docs as Record<string, string[]>;
+    expect(docs.command.length).toBeGreaterThan(0);
+  });
+
+  it("outputs valid JSON for specific command with --format json", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization", "command", "CreateCompany", "json");
+    expect(exitCode).toBe(0);
+
+    const parsed = JSON.parse(logs.join("\n")) as Record<string, unknown>;
+    expect(parsed).toHaveProperty("module", "organization");
+    expect(parsed).toHaveProperty("type", "command");
+    expect(parsed).toHaveProperty("name", "CreateCompany");
+    expect(parsed).toHaveProperty("content");
+    expect(typeof parsed.content).toBe("string");
+    expect(parsed.content as string).toContain("# CreateCompany");
+  });
+
+  it("returns error for unknown doc name", () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModule("organization", "command", "Nonexistent");
+    expect(exitCode).toBe(1);
+
+    const output = errors.join("\n");
+    expect(output).toContain("Doc not found: organization/command/Nonexistent");
+    expect(output).toContain("Available commands:");
+  });
+});

package/src/commands/doc/module.ts

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../util";
+import { MODULE_PATHS } from "../lib/paths";
+
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+
+const DOC_TYPE_MAP: Record<string, string> = {
+  command: MODULE_PATHS.docs.commands,
+  query: MODULE_PATHS.docs.queries,
+  model: MODULE_PATHS.docs.models,
+  feature: MODULE_PATHS.docs.features,
+};
+
+function listDocNames(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""))
+    .sort();
+}
+
+function formatDocList(type: string, names: string[]): string {
+  if (names.length === 0) return "";
+  return `${type}: ${names.join(", ")}`;
+}
+
+export function runDocModule(
+  moduleName: string,
+  docType?: string,
+  docName?: string,
+  format = "text",
+): number {
+  if (!existsSync(MODULES_DIR) || EXCLUDED_DIRS.has(moduleName)) {
+    console.error(`Module not found: ${moduleName}`);
+    return 1;
+  }
+
+  const modDir = join(MODULES_DIR, moduleName);
+  if (!existsSync(modDir)) {
+    console.error(`Module not found: ${moduleName}`);
+    const available = readdirSync(MODULES_DIR, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name))
+      .map((d) => d.name)
+      .sort();
+    console.error(`Available modules: ${available.join(", ")}`);
+    return 1;
+  }
+
+  // Level 3: specific doc
+  if (docType && docName) {
+    const docSubdir = DOC_TYPE_MAP[docType];
+    if (!docSubdir) {
+      console.error(`Unknown doc type: ${docType}`);
+      console.error(`Available types: ${Object.keys(DOC_TYPE_MAP).join(", ")}`);
+      return 1;
+    }
+
+    const docPath = join(modDir, docSubdir, `${docName}.md`);
+    if (!existsSync(docPath)) {
+      console.error(`Doc not found: ${moduleName}/${docType}/${docName}`);
+      const available = listDocNames(join(modDir, docSubdir));
+      if (available.length > 0) {
+        console.error(`Available ${docType}s: ${available.join(", ")}`);
+      } else {
+        console.error(`No ${docType} docs found for ${moduleName}`);
+      }
+      return 1;
+    }
+
+    const content = readFileSync(docPath, "utf-8");
+    if (format === "json") {
+      console.log(
+        JSON.stringify({ module: moduleName, type: docType, name: docName, content }, null, 2),
+      );
+    } else {
+      console.log(content);
+    }
+    return 0;
+  }
+
+  // Level 2: full module detail
+  const readmePath = join(modDir, "README.md");
+  const readme = existsSync(readmePath) ? readFileSync(readmePath, "utf-8") : "";
+
+  const docs: Record<string, string[]> = {};
+  for (const [type, subdir] of Object.entries(DOC_TYPE_MAP)) {
+    const names = listDocNames(join(modDir, subdir));
+    if (names.length > 0) docs[type] = names;
+  }
+
+  if (format === "json") {
+    console.log(JSON.stringify({ module: moduleName, readme, docs }, null, 2));
+  } else {
+    if (readme) {
+      console.log(readme);
+    } else {
+      console.log(`# ${moduleName}\n\nNo README found.\n`);
+    }
+
+    const sections: string[] = [];
+    for (const [type, names] of Object.entries(docs)) {
+      sections.push(formatDocList(type, names));
+    }
+
+    if (sections.length > 0) {
+      console.log("\n## Available Documentation\n");
+      console.log(sections.join("\n"));
+    }
+  }
+
+  return 0;
+}