@ankhorage/paradox 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.4
+
+### Patch Changes
+
+- 0255235: Full documentation of repo
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.2](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.3](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -142,6 +142,7 @@ graph TD
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_exports_ts
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_graphs_ts
   module_src_analyze_analyze_ts --> module_src_analyze_sequenceScenarios_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_sourceFunctions_ts
   module_src_analyze_analyze_ts --> module_src_analyze_types_ts
   module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
   module_src_analyze_analyze_ts --> module_src_config_types_ts
@@ -224,6 +225,11 @@ graph TD
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_usage_ts
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_getParadoxComment_ts
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_sourceFunctions_ts["src/analyze/sourceFunctions.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_sourceFunctions_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_types_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_utils_parseParadoxComment_ts
   module_src_analyze_types_ts["src/analyze/types.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_types_ts
   module_src_analyze_usage_ts["src/analyze/usage.ts"]
@@ -316,7 +322,7 @@ graph TD
 
 ## Public API
 
-### Configuration
+### Config
 
 <details>
 <summary>defineParadoxConfig</summary>

package/dist/analyze/analyze.d.ts

@@ -1,5 +1,8 @@
 import type { ParadoxConfig } from '../config/types.js';
 import type { AnalysisResult } from './types.js';
+/***
+ * Analyzes a package and returns the complete documentation input model.
+ */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;
 }): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -9,7 +9,11 @@ import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
 import { analyzeSequenceScenarios } from './sequenceScenarios.js';
+import { analyzeSourceFunctions } from './sourceFunctions.js';
 import { createUsageFromPackageJson } from './usage.js';
+/***
+ * Analyzes a package and returns the complete documentation input model.
+ */
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
@@ -21,6 +25,7 @@ export async function analyze(config, runtime) {
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
     const modules = analyzeModules(project, { root, entrypoints });
+    const sourceFunctions = analyzeSourceFunctions(project, root);
     const sequenceScenarios = analyzeSequenceScenarios({ project, root, pkg, exports });
     const configExport = configMetadata
         ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
@@ -49,6 +54,7 @@ export async function analyze(config, runtime) {
         description: config.docs?.description ?? pkg.description ?? null,
         exports,
         components,
+        sourceFunctions,
         entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
         modules,
         badges,
@@ -64,6 +70,9 @@ export async function analyze(config, runtime) {
         graphs,
     };
 }
+/***
+ * Converts semantic type members into serializable analysis output.
+ */
 function mapTypeMembers(members) {
     return members.map((member) => ({
         name: member.name,
@@ -75,6 +84,9 @@ function mapTypeMembers(members) {
         ...(member.children ? { children: mapTypeMembers(member.children) } : {}),
     }));
 }
+/***
+ * Reads package metadata from the analyzed package root.
+ */
 async function readPackageJson(root) {
     const raw = await readFile(join(root, 'package.json'), 'utf-8');
     return JSON.parse(raw);

package/dist/analyze/badges.js

@@ -132,6 +132,9 @@ export async function analyzeBadges(root, pkg) {
     });
     return sortBadges(badges);
 }
+/***
+ * Checks whether any candidate file exists under the repository root.
+ */
 async function hasAnyFile(root, paths) {
     for (const relativePath of paths) {
         if (await fileExists(join(root, relativePath))) {
@@ -140,18 +143,30 @@ async function hasAnyFile(root, paths) {
     }
     return false;
 }
+/***
+ * Reads tsconfig metadata and detects strict TypeScript mode.
+ */
 async function hasTypeScriptStrictMode(root) {
     const tsconfig = await readJsonFile(join(root, 'tsconfig.json'));
     return tsconfig?.compilerOptions?.strict === true;
 }
+/***
+ * Reads the line coverage percentage from a coverage summary file when present.
+ */
 async function readCoveragePercent(root) {
     const coverage = await readJsonFile(join(root, 'coverage', 'coverage-summary.json'));
     const value = coverage?.total?.lines?.pct;
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+/***
+ * Formats integer and fractional percentages for badge labels.
+ */
 function formatPercent(value) {
     return Number.isInteger(value) ? `${value}` : value.toFixed(1);
 }
+/***
+ * Selects the coverage badge color from the coverage percentage.
+ */
 function getCoverageColor(value) {
     if (value >= 90)
         return '0a7f3f';
@@ -161,12 +176,21 @@ function getCoverageColor(value) {
         return 'ca8a04';
     return 'dc2626';
 }
+/***
+ * Checks whether a named package script is configured.
+ */
 function hasScript(pkg, name) {
     return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
 }
+/***
+ * Checks whether a package script contains a specific command fragment.
+ */
 function scriptContains(pkg, name, command) {
     return pkg.scripts?.[name]?.includes(command) ?? false;
 }
+/***
+ * Detects whether package metadata or workflows indicate Bun support.
+ */
 function supportsBun(pkg, workflowFiles) {
     if (pkg.packageManager?.startsWith('bun@') ?? false) {
         return true;
@@ -178,6 +202,9 @@ function supportsBun(pkg, workflowFiles) {
         workflow.includes('bun install') ||
         /\bbun(?:x)?\b/.test(workflow));
 }
+/***
+ * Checks whether any workflow file invokes a named package script.
+ */
 function workflowRunsScript(workflowFiles, scriptName) {
     const escaped = escapeRegExp(scriptName);
     const patterns = [
@@ -188,9 +215,15 @@ function workflowRunsScript(workflowFiles, scriptName) {
     ];
     return workflowFiles.some((workflow) => patterns.some((pattern) => pattern.test(workflow)));
 }
+/***
+ * Escapes regular expression syntax in a script name.
+ */
 function escapeRegExp(value) {
     return value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/***
+ * Reads all GitHub Actions workflow files from the repository.
+ */
 async function readWorkflowFiles(root) {
     const workflowsPath = join(root, '.github', 'workflows');
     const entries = await readDirectory(workflowsPath);
@@ -200,6 +233,9 @@ async function readWorkflowFiles(root) {
         .map((entry) => readFile(join(workflowsPath, entry), 'utf-8')));
     return contents;
 }
+/***
+ * Reads a directory and treats a missing path as an empty directory.
+ */
 async function readDirectory(path) {
     try {
         return await readdir(path);
@@ -211,9 +247,15 @@ async function readDirectory(path) {
         throw new Error(`Unable to read workflow directory: ${path}`, { cause: error });
     }
 }
+/***
+ * Checks whether an unknown error is a file-not-found filesystem error.
+ */
 function isNotFoundError(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+/***
+ * Reads and parses a JSON file, returning null when the file does not exist.
+ */
 async function readJsonFile(path) {
     let content;
     try {
@@ -232,6 +274,9 @@ async function readJsonFile(path) {
         throw new Error(`Unable to parse JSON metadata file: ${path}`, { cause: error });
     }
 }
+/***
+ * Checks whether a filesystem path exists.
+ */
 async function fileExists(path) {
     try {
         await access(path);
@@ -244,12 +289,18 @@ async function fileExists(path) {
         throw error;
     }
 }
+/***
+ * Sorts badges into the stable preferred display order.
+ */
 function sortBadges(badges) {
     return [...badges].sort((left, right) => {
         const order = getBadgeOrder(left.id) - getBadgeOrder(right.id);
         return order !== 0 ? order : left.id.localeCompare(right.id);
     });
 }
+/***
+ * Returns the configured display order index for a badge id.
+ */
 function getBadgeOrder(id) {
     const index = BADGE_ORDER.indexOf(id);
     return index === -1 ? BADGE_ORDER.length : index;

package/dist/analyze/modules.js

@@ -36,9 +36,15 @@ export function analyzeModules(project, options) {
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
+/***
+ * Returns unique string values sorted for deterministic generated output.
+ */
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }

package/dist/analyze/sourceFunctions.d.ts

@@ -0,0 +1,6 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisSourceFunction } from './types.js';
+/***
+ * Collects callable declarations from analyzed source files for source-area documentation.
+ */
+export declare function analyzeSourceFunctions(project: Project, root: string): AnalysisSourceFunction[];

package/dist/analyze/sourceFunctions.js

@@ -0,0 +1,64 @@
+import { relative } from 'node:path';
+import { Node } from 'ts-morph';
+import { getParadoxComment } from './utils/getParadoxComment.js';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+/***
+ * Collects callable declarations from analyzed source files for source-area documentation.
+ */
+export function analyzeSourceFunctions(project, root) {
+    return project
+        .getSourceFiles()
+        .flatMap((sourceFile) => {
+        if (sourceFile.isDeclarationFile())
+            return [];
+        const filePath = toPosixPath(relative(root, sourceFile.getFilePath()));
+        if (!filePath.startsWith('src/'))
+            return [];
+        return sourceFile.getDescendants().flatMap((node) => {
+            if (Node.isFunctionDeclaration(node)) {
+                const name = node.getName();
+                if (name === undefined)
+                    return [];
+                return [createSourceFunction(name, node, root)];
+            }
+            if (Node.isVariableDeclaration(node)) {
+                const initializer = node.getInitializer();
+                if (initializer === undefined ||
+                    (!Node.isArrowFunction(initializer) && !Node.isFunctionExpression(initializer))) {
+                    return [];
+                }
+                return [createSourceFunction(node.getName(), node, root)];
+            }
+            return [];
+        });
+    })
+        .sort((left, right) => left.sourceLocation.filePath === right.sourceLocation.filePath
+        ? left.sourceLocation.line - right.sourceLocation.line
+        : left.sourceLocation.filePath.localeCompare(right.sourceLocation.filePath));
+}
+/***
+ * Converts a callable declaration into source documentation metadata.
+ */
+function createSourceFunction(name, node, root) {
+    const sourceFile = node.getSourceFile();
+    const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
+    const rawComment = getParadoxComment(node);
+    const parsedComment = rawComment
+        ? parseParadoxComment(rawComment)
+        : { description: null, isReadme: false };
+    return {
+        name,
+        description: parsedComment.description,
+        sourceLocation: {
+            filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+            line,
+            column,
+        },
+    };
+}
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/types.d.ts

@@ -95,6 +95,11 @@ export interface AnalysisSequenceScenario {
     description: string | null;
     isReadme: boolean;
 }
+export interface AnalysisSourceFunction {
+    name: string;
+    description: string | null;
+    sourceLocation: AnalysisSourceLocation;
+}
 interface AnalysisTypeMember {
     name: string;
     type: string;
@@ -141,6 +146,7 @@ export interface AnalysisResult {
     description: string | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];
+    sourceFunctions: AnalysisSourceFunction[];
     entrypoints: string[];
     modules: AnalysisModule[];
     badges: AnalysisBadge[];

package/dist/analyze/usage.d.ts

@@ -10,4 +10,7 @@ export interface PackageJsonModel {
     eslintConfig?: unknown;
     prettier?: unknown;
 }
+/***
+ * Builds installation and executable usage commands from package metadata.
+ */
 export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

package/dist/analyze/usage.js

@@ -1,3 +1,6 @@
+/***
+ * Builds installation and executable usage commands from package metadata.
+ */
 export function createUsageFromPackageJson(pkg) {
     if (pkg.bin == null)
         return null;
@@ -35,6 +38,9 @@ export function createUsageFromPackageJson(pkg) {
         })),
     };
 }
+/***
+ * Extracts the unscoped package name from a package id.
+ */
 function getPackageBaseName(packageName) {
     return packageName.split('/').pop() ?? packageName;
 }

package/dist/model/buildModel.d.ts

@@ -80,6 +80,15 @@ interface BuildModelInput {
             description: string | null;
         }[];
     }[];
+    sourceFunctions: {
+        name: string;
+        description: string | null;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+    }[];
     sequenceScenarios: {
         kind: 'bin' | 'export';
         name: string;

package/dist/model/buildModel.js

@@ -46,6 +46,15 @@ export function buildModel(analysis) {
             .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
+        sourceFunctions: analysis.sourceFunctions.map((sourceFunction) => ({
+            name: sourceFunction.name,
+            description: sourceFunction.description,
+            sourceLocation: {
+                filePath: sourceFunction.sourceLocation.filePath,
+                line: sourceFunction.sourceLocation.line,
+                column: sourceFunction.sourceLocation.column,
+            },
+        })),
         sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({
             kind: scenario.kind,
             name: scenario.name,
@@ -62,6 +71,9 @@ export function buildModel(analysis) {
         },
     };
 }
+/***
+ * Maps one analyzed export into the serializable documentation shape.
+ */
 function mapExport(item, exportNames) {
     return {
         name: item.name,
@@ -102,6 +114,9 @@ function mapExport(item, exportNames) {
         }))),
     };
 }
+/***
+ * Maps an analyzed component while preserving export metadata when available.
+ */
 function mapComponent(component, exportModel) {
     return {
         name: component.name,
@@ -124,6 +139,9 @@ function mapComponent(component, exportModel) {
         }))),
     };
 }
+/***
+ * Finds the conventional config factory export for a config type when present.
+ */
 function findConfigFactoryName(configExportName, exportNames) {
     const prefix = configExportName.endsWith('Config')
         ? configExportName.slice(0, -'Config'.length)
@@ -131,10 +149,16 @@ function findConfigFactoryName(configExportName, exportNames) {
     const expectedFactoryName = `define${prefix}Config`;
     return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
 }
+/***
+ * Derives the default config file name from a package id.
+ */
 function getDefaultConfigFileName(packageId) {
     const packageBaseName = packageId.split('/').pop() ?? packageId;
     return `${packageBaseName}.config.ts`;
 }
+/***
+ * Returns a copy of items sorted by their `name` property.
+ */
 function sortByName(items) {
     return [...items].sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/model/types.d.ts

@@ -12,6 +12,7 @@ export interface DocumentationModel {
     modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
+    sourceFunctions: SourceFunctionModel[];
     sequenceScenarios: SequenceScenarioModel[];
     graphs: GraphModel;
 }
@@ -60,6 +61,11 @@ export interface ComponentModel {
     exportPaths: string[];
     props: PropModel[];
 }
+interface SourceFunctionModel {
+    name: string;
+    description: string | null;
+    sourceLocation: SourceLocationModel;
+}
 export interface SequenceScenarioModel {
     kind: 'bin' | 'export';
     name: string;

package/dist/paths/policy.d.ts

@@ -1,7 +1,19 @@
 import type { ParadoxConfig } from '../config/types.js';
+/***
+ * Searches upward from a start directory until it finds a supported Paradox config file.
+ */
 export declare function findParadoxConfigFile(startDir: string): Promise<string | null>;
+/***
+ * Loads a Paradox config module and returns its default export or an empty config.
+ */
 export declare function loadParadoxConfig(configFilePath: string): Promise<ParadoxConfig>;
+/***
+ * Resolves and validates the package root from config and config directory.
+ */
 export declare function resolvePackageRoot(config: ParadoxConfig, configDir: string): Promise<string>;
+/***
+ * Resolves the configured output directory and enforces that it stays inside the package root.
+ */
 export declare function resolveOutputRoot(config: ParadoxConfig, packageRoot: string): {
     outputDir: string;
     outputRoot: string;

package/dist/paths/policy.js

@@ -7,6 +7,9 @@ const CONFIG_FILENAMES = [
     'paradox.config.mjs',
     'paradox.config.cjs',
 ];
+/***
+ * Searches upward from a start directory until it finds a supported Paradox config file.
+ */
 export async function findParadoxConfigFile(startDir) {
     let current = resolve(startDir);
     let parent = dirname(current);
@@ -26,11 +29,17 @@ export async function findParadoxConfigFile(startDir) {
     }
     return null;
 }
+/***
+ * Loads a Paradox config module and returns its default export or an empty config.
+ */
 export async function loadParadoxConfig(configFilePath) {
     const url = pathToFileURL(configFilePath).href;
     const mod = (await import(url));
     return mod.default ?? {};
 }
+/***
+ * Resolves and validates the package root from config and config directory.
+ */
 export async function resolvePackageRoot(config, configDir) {
     const configuredRoot = config.package?.root;
     const resolvedRoot = configuredRoot
@@ -41,6 +50,9 @@ export async function resolvePackageRoot(config, configDir) {
     await assertPathExists(join(resolvedRoot, 'package.json'), `Unable to find package.json at resolved package root: ${resolvedRoot}`);
     return resolvedRoot;
 }
+/***
+ * Resolves the configured output directory and enforces that it stays inside the package root.
+ */
 export function resolveOutputRoot(config, packageRoot) {
     const outputDir = config.output?.dir ?? 'paradox';
     validateOutputDir(outputDir);
@@ -48,6 +60,9 @@ export function resolveOutputRoot(config, packageRoot) {
     assertWithinRoot(outputRoot, packageRoot, `Resolved output directory escapes package root: ${outputRoot}`);
     return { outputDir, outputRoot };
 }
+/***
+ * Checks whether a filesystem path can be accessed.
+ */
 async function pathExists(path) {
     try {
         await access(path);
@@ -57,11 +72,17 @@ async function pathExists(path) {
         return false;
     }
 }
+/***
+ * Throws a supplied error message when a required path does not exist.
+ */
 async function assertPathExists(path, message) {
     if (!(await pathExists(path))) {
         throw new Error(message);
     }
 }
+/***
+ * Validates an output directory string before resolving it against the package root.
+ */
 function validateOutputDir(outputDir) {
     const trimmed = outputDir.trim();
     if (trimmed.length === 0) {
@@ -74,18 +95,22 @@ function validateOutputDir(outputDir) {
     if (isAbsolute(normalized)) {
         throw new Error('Invalid output.dir: must be a relative path inside the package root (absolute paths are not allowed).');
     }
-    // Reject explicit parent traversal to keep writes deterministic and scoped.
     for (const segment of splitPathSegments(trimmed)) {
         if (segment === '..') {
             throw new Error('Invalid output.dir: must not contain ".." path segments.');
         }
     }
 }
+/***
+ * Splits a configured path into normalized non-empty path segments.
+ */
 function splitPathSegments(path) {
-    // Treat both separators as potential delimiters to stay robust across platforms/config styles.
     const normalized = path.replaceAll('\\', '/');
     return normalized.split('/').filter((segment) => segment.length > 0 && segment !== '.');
 }
+/***
+ * Throws when a resolved path is outside the expected package root.
+ */
 function assertWithinRoot(resolvedPath, root, message) {
     const rel = relative(root, resolvedPath);
     if (rel === '')

package/dist/render/renderers/html.js

@@ -2,18 +2,8 @@
  * Renders a deterministic static HTML documentation app.
  */
 export function renderHtml({ diagrams, model, }) {
-    const navigationItems = [
-        ...model.exports.map((item) => ({
-            href: `#symbol-${toAnchorId(item.name)}`,
-            label: item.name,
-            meta: `${item.kind} • ${item.modulePath}`,
-        })),
-        ...model.components.map((component) => ({
-            href: `#component-${toAnchorId(component.name)}`,
-            label: component.name,
-            meta: `component • ${component.modulePath}`,
-        })),
-    ].sort((left, right) => left.label.localeCompare(right.label));
+    const sourceAreas = getSourceAreas(model);
+    const cliScenarios = getReadmeCliScenarios(model);
     const exportsByModule = groupBy(model.exports, (item) => item.modulePath);
     return {
         indexHtml: `<!doctype html>
@@ -33,6 +23,7 @@ export function renderHtml({ diagrams, model, }) {
       body { margin: 0; }
       a { color: #2459d3; text-decoration: none; }
       a:hover { text-decoration: underline; }
+      button { font: inherit; }
       code, pre { font-family: "SFMono-Regular", ui-monospace, SFMono-Regular, Menlo, monospace; }
       .layout {
         display: grid;
@@ -48,9 +39,7 @@ export function renderHtml({ diagrams, model, }) {
         max-height: 100vh;
         overflow: auto;
       }
-      .content {
-        padding: 2rem;
-      }
+      .content { padding: 2rem; }
       .panel, .item {
         background: #ffffff;
         border: 1px solid #d8dfec;
@@ -80,7 +69,28 @@ export function renderHtml({ diagrams, model, }) {
         padding: 0;
         margin: 0;
       }
-      .nav-list li + li { margin-top: 0.8rem; }
+      .nav-list li + li { margin-top: 0.5rem; }
+      .nav-button {
+        width: 100%;
+        display: block;
+        border: 0;
+        border-radius: 0.7rem;
+        background: transparent;
+        color: #24427a;
+        cursor: pointer;
+        padding: 0.55rem 0.7rem;
+        text-align: left;
+      }
+      .nav-button:hover, .nav-button[aria-current="page"] {
+        background: #e8eefb;
+        text-decoration: none;
+      }
+      .nav-button small {
+        display: block;
+        color: #5e6d8c;
+        margin-top: 0.15rem;
+      }
+      .view[hidden] { display: none; }
       .muted { color: #5e6d8c; }
       .chips { display: flex; flex-wrap: wrap; gap: 0.5rem; padding: 0; list-style: none; }
       .chip {
@@ -115,61 +125,64 @@ export function renderHtml({ diagrams, model, }) {
         <p class="muted">Generated with Paradox</p>
         <h1>${escapeHtml(model.packageName)}</h1>
         <p>${escapeHtml(model.description ?? 'Deterministic package documentation.')}</p>
-        <input id="search" class="search" type="search" placeholder="Search symbols, files, and metadata" />
-        <ul class="nav-list">
-          ${navigationItems
-            .map((item) => `<li><a href="${escapeAttribute(item.href)}">${escapeHtml(item.label)}</a><div class="muted">${escapeHtml(item.meta)}</div></li>`)
-            .join('')}
-        </ul>
+        <input id="search" class="search" type="search" placeholder="Search current view" />
+        <nav aria-label="Documentation sections">
+          <ul class="nav-list">
+            <li>
+              <button class="nav-button" type="button" data-target="home" aria-current="page">
+                Home
+                <small>Overview, CLI, public API, diagrams</small>
+              </button>
+            </li>
+            ${sourceAreas.map(renderSourceNavItem).join('')}
+          </ul>
+        </nav>
       </aside>
       <main class="content">
-        <section class="panel">
-          <h2>Package overview</h2>
-          <div class="summary">
-            <div><strong>${model.exports.length}</strong><span class="muted">public exports</span></div>
-            <div><strong>${model.components.length}</strong><span class="muted">components</span></div>
-            <div><strong>${model.modules.length}</strong><span class="muted">modules</span></div>
-            <div><strong>${model.entrypoints.length}</strong><span class="muted">entrypoints</span></div>
-          </div>
-          <h3>Entrypoints</h3>
-          <ul class="meta-list">
-            ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
-          </ul>
-        </section>
-        <section class="panel">
-          <h2>Modules</h2>
-          ${model.modules.map(renderModuleCard).join('')}
-        </section>
-        <section class="panel">
-          <h2>Exports by module</h2>
-          ${[...exportsByModule.entries()]
-            .map(([modulePath, exports]) => `
-                <section>
-                  <h3>${escapeHtml(modulePath)}</h3>
-                  ${exports.map((item) => renderExportCard(item)).join('')}
-                </section>`)
-            .join('')}
-        </section>
-        <section class="panel">
-          <h2>Component registry</h2>
-          ${model.components.length === 0 ? '<p class="empty">No components were detected.</p>' : model.components.map(renderComponentCard).join('')}
-        </section>
-        <section class="panel">
-          <h2>Diagrams</h2>
-          ${diagrams.map(renderDiagramCard).join('')}
+        <section id="view-home" class="view" data-view="home">
+          ${renderHomeView(model, diagrams, cliScenarios, exportsByModule)}
         </section>
+        ${sourceAreas.map(renderSourceAreaView).join('')}
       </main>
     </div>
     <script>
       const search = document.getElementById('search');
-      const items = Array.from(document.querySelectorAll('[data-search]'));
-      search?.addEventListener('input', () => {
-        const value = search.value.trim().toLowerCase();
+      const navButtons = Array.from(document.querySelectorAll('[data-target]'));
+      const views = Array.from(document.querySelectorAll('[data-view]'));
+
+      function getActiveView() {
+        return document.querySelector('[data-view]:not([hidden])');
+      }
+
+      function applySearch() {
+        const value = search?.value.trim().toLowerCase() || '';
+        const activeView = getActiveView();
+        const items = Array.from(activeView?.querySelectorAll('[data-search]') || []);
+
         for (const item of items) {
           const haystack = (item.getAttribute('data-search') || '').toLowerCase();
           item.style.display = value === '' || haystack.includes(value) ? '' : 'none';
         }
-      });
+      }
+
+      for (const button of navButtons) {
+        button.addEventListener('click', () => {
+          const target = button.getAttribute('data-target');
+
+          for (const view of views) {
+            view.hidden = view.getAttribute('data-view') !== target;
+          }
+
+          for (const item of navButtons) {
+            item.setAttribute('aria-current', item === button ? 'page' : 'false');
+          }
+
+          if (search) search.value = '';
+          applySearch();
+        });
+      }
+
+      search?.addEventListener('input', applySearch);
     </script>
     <script type="module">
       import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
@@ -180,6 +193,123 @@ export function renderHtml({ diagrams, model, }) {
 `,
     };
 }
+/***
+ * Renders the Home view that keeps public API and package-level information together.
+ */
+function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
+    return `
+    <section class="panel">
+      <h2>Package overview</h2>
+      <div class="summary">
+        <div><strong>${model.exports.length}</strong><span class="muted">public exports</span></div>
+        <div><strong>${model.components.length}</strong><span class="muted">components</span></div>
+        <div><strong>${model.modules.length}</strong><span class="muted">modules</span></div>
+        <div><strong>${model.entrypoints.length}</strong><span class="muted">entrypoints</span></div>
+      </div>
+      <h3>Entrypoints</h3>
+      <ul class="meta-list">
+        ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
+      </ul>
+    </section>
+    ${cliScenarios.length > 0 ? renderCliPanel(model, diagrams, cliScenarios) : ''}
+    <section class="panel">
+      <h2>Modules</h2>
+      ${model.modules.map(renderModuleCard).join('')}
+    </section>
+    <section class="panel">
+      <h2>Public API</h2>
+      ${[...exportsByModule.entries()]
+        .map(([modulePath, exports]) => `
+            <section>
+              <h3>${escapeHtml(modulePath)}</h3>
+              ${exports.map((item) => renderExportCard(item)).join('')}
+            </section>`)
+        .join('')}
+    </section>
+    <section class="panel">
+      <h2>Component registry</h2>
+      ${model.components.length === 0 ? '<p class="empty">No components were detected.</p>' : model.components.map(renderComponentCard).join('')}
+    </section>
+    <section class="panel">
+      <h2>Diagrams</h2>
+      ${diagrams.map(renderDiagramCard).join('')}
+    </section>`;
+}
+/***
+ * Renders the Home CLI chapter for detected bin scenarios.
+ */
+function renderCliPanel(model, diagrams, scenarios) {
+    return `<section class="panel" data-search="cli ${scenarios.map((scenario) => scenario.name).join(' ')}">
+    <h2>CLI</h2>
+    ${scenarios
+        .map((scenario) => {
+        const command = model.usage?.commands.find((item) => item.name === scenario.name);
+        const diagram = findScenarioDiagram(diagrams, scenario);
+        return `<article class="item" data-search="${escapeAttribute([scenario.name, scenario.description ?? '', command?.command ?? ''].join(' '))}">
+          <h3>${escapeHtml(scenario.name)}</h3>
+          ${scenario.description === null ? '' : `<p>${escapeHtml(scenario.description)}</p>`}
+          ${command === undefined ? '' : `<pre>${escapeHtml(command.command)}</pre>`}
+          ${diagram === undefined ? '' : renderDiagramCard(diagram)}
+        </article>`;
+    })
+        .join('')}
+  </section>`;
+}
+/***
+ * Renders one source file entry in the left navigation.
+ */
+function renderSourceNavItem(area) {
+    return `<li>
+    <button class="nav-button" type="button" data-target="${escapeAttribute(area.path)}">
+      ${escapeHtml(area.path)}
+      <small>${area.functions.length} function${area.functions.length === 1 ? '' : 's'}</small>
+    </button>
+  </li>`;
+}
+/***
+ * Renders the right-hand source area view for a selected file.
+ */
+function renderSourceAreaView(area) {
+    return `<section id="view-${toAnchorId(area.path)}" class="view" data-view="${escapeAttribute(area.path)}" hidden>
+    <section class="panel">
+      <h2>${escapeHtml(area.path)}</h2>
+      ${area.functions.map(renderSourceFunctionCard).join('')}
+    </section>
+  </section>`;
+}
+/***
+ * Renders one source function card in a source-area view.
+ */
+function renderSourceFunctionCard(item) {
+    return `<article class="item" data-search="${escapeAttribute([item.name, item.sourceLocation.filePath, item.description ?? ''].join(' '))}">
+    <h3>${escapeHtml(item.name)}</h3>
+    <p class="muted"><code>${escapeHtml(item.sourceLocation.filePath)}:${item.sourceLocation.line}:${item.sourceLocation.column}</code></p>
+    ${item.description === null ? '<p class="empty">No description available.</p>' : `<p>${escapeHtml(item.description)}</p>`}
+  </article>`;
+}
+/***
+ * Groups analyzed source functions by their source file path.
+ */
+function getSourceAreas(model) {
+    return [...groupBy(model.sourceFunctions, (item) => item.sourceLocation.filePath).entries()]
+        .map(([path, functions]) => ({ path, functions }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+/***
+ * Selects bin scenarios that should be shown on the Home page.
+ */
+function getReadmeCliScenarios(model) {
+    return model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
+}
+/***
+ * Finds the generated Mermaid artifact for a sequence scenario.
+ */
+function findScenarioDiagram(diagrams, scenario) {
+    return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
+}
+/***
+ * Renders module metadata on the Home page.
+ */
 function renderModuleCard(module) {
     return `<article class="item" data-search="${escapeAttribute([module.path, ...module.dependencies, ...module.exports].join(' '))}">
     <h3>${escapeHtml(module.path)}</h3>
@@ -188,6 +318,9 @@ function renderModuleCard(module) {
     <p><strong>Exports:</strong> ${renderInlineCodeList(module.exports)}</p>
   </article>`;
 }
+/***
+ * Renders one public API export card on the Home page.
+ */
 function renderExportCard(item) {
     return `<article class="item" id="symbol-${toAnchorId(item.name)}" data-search="${escapeAttribute([
         item.name,
@@ -206,6 +339,9 @@ function renderExportCard(item) {
     ${item.members.length > 0 ? renderMemberTable(item) : ''}
   </article>`;
 }
+/***
+ * Renders all call signatures for a public API export.
+ */
 function renderSignatureBlock(item) {
     return item.signatures
         .map((signature) => `<div>
@@ -230,6 +366,9 @@ function renderSignatureBlock(item) {
       </div>`)
         .join('');
 }
+/***
+ * Renders the members table for a type-like public API export.
+ */
 function renderMemberTable(item) {
     return `<table>
     <thead><tr><th>Member</th><th>Kind</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
@@ -246,6 +385,9 @@ function renderMemberTable(item) {
     </tbody>
   </table>`;
 }
+/***
+ * Renders one detected component card on the Home page.
+ */
 function renderComponentCard(component) {
     return `<article class="item" id="component-${toAnchorId(component.name)}" data-search="${escapeAttribute([
         component.name,
@@ -272,6 +414,9 @@ function renderComponentCard(component) {
     </table>
   </article>`;
 }
+/***
+ * Renders one Mermaid diagram card.
+ */
 function renderDiagramCard(diagram) {
     return `<article class="item" data-search="${escapeAttribute(`${diagram.title} ${diagram.path}`)}">
     <h3>${escapeHtml(diagram.title)}</h3>
@@ -283,17 +428,26 @@ function renderDiagramCard(diagram) {
     </details>
   </article>`;
 }
+/***
+ * Renders an inline comma-separated list of code values.
+ */
 function renderInlineCodeList(values) {
     if (values.length === 0) {
         return '<span class="empty">None</span>';
     }
     return values.map((value) => `<code>${escapeHtml(value)}</code>`).join(', ');
 }
+/***
+ * Renders a compact chip list for related symbols.
+ */
 function renderChipList(values) {
     return `<ul class="chips">${values
         .map((value) => `<li class="chip">${escapeHtml(value)}</li>`)
         .join('')}</ul>`;
 }
+/***
+ * Groups items by a string key and returns deterministic key order.
+ */
 function groupBy(items, key) {
     const groups = new Map();
     for (const item of items) {
@@ -308,12 +462,28 @@ function groupBy(items, key) {
     }
     return new Map([...groups.entries()].sort(([left], [right]) => left.localeCompare(right)));
 }
+/***
+ * Converts a label to a stable HTML anchor id fragment.
+ */
 function toAnchorId(value) {
     return value
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
 }
+/***
+ * Converts a scenario name to the generated Mermaid file stem.
+ */
+function toFileStem(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+/***
+ * Escapes user-controlled text for safe HTML rendering.
+ */
 function escapeHtml(value) {
     return value
         .replaceAll('&', '&amp;')
@@ -322,6 +492,9 @@ function escapeHtml(value) {
         .replaceAll('"', '&quot;')
         .replaceAll("'", '&#39;');
 }
+/***
+ * Escapes text for use inside HTML attribute values.
+ */
 function escapeAttribute(value) {
     return escapeHtml(value).replaceAll('\n', '&#10;');
 }

package/dist/render/renderers/markdown.js

@@ -255,7 +255,7 @@ function getReadmeItemName(item) {
 }
 function getReadmeCategory(modulePath, name) {
     if (modulePath.includes('/config/'))
-        return 'Configuration';
+        return 'Config';
     if (modulePath.includes('/primitives/'))
         return 'Primitives';
     if (modulePath.includes('/components/'))
@@ -364,7 +364,7 @@ function toFileStem(value) {
         .toLowerCase();
 }
 const CATEGORY_ORDER = [
-    'Configuration',
+    'Config',
     'Primitives',
     'Components',
     'Patterns',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {