@ankhorage/paradox 0.0.10 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.0
+
+### Minor Changes
+
+- dd41897: Generate compact README docs from `@readme` symbols.
+
 ## 0.0.10
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,41 @@
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.9](./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.0.10](./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.
 
-## Usage
+## Installation
 
 ```bash
 bunx @ankhorage/paradox
 ```
 
+## Documentation Tags
+
+<details>
+<summary>@readme</summary>
+
+Includes a documentation block or exported symbol in README output.
+
+</details>
+
+<details>
+<summary>@config</summary>
+
+Marks a type or interface as part of the Paradox configuration model. `@config` alone does not imply README inclusion; use `@config` plus `@readme` for README output.
+
+</details>
+
+<details>
+<summary>@example</summary>
+
+Adds a titled fenced code example to the generated documentation for a symbol.
+
+</details>
+
 ## Configuration
 
 Create a `paradox.config.ts` file:
@@ -22,14 +48,17 @@ export default defineParadoxConfig({
 });
 ```
 
-### Configuration options
+<details>
+<summary>Configuration options</summary>
 
 | Field   | Type                                                      | Required | Default | Description |
 | ------- | --------------------------------------------------------- | -------- | ------- | ----------- |
-| mode    | `'safe' \| 'write' \| undefined`                          | no       |         |             |
-| docs    | `{ title?: string; description?: string; } \| undefined`  | no       |         |             |
-| package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no       |         |             |
-| output  | `{ dir?: string; } \| undefined`                          | no       |         |             |
+| mode    | `'safe' \| 'write' \| undefined`                          | no       | —       |             |
+| docs    | `{ title?: string; description?: string; } \| undefined`  | no       | —       |             |
+| package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no       | —       |             |
+| output  | `{ dir?: string; } \| undefined`                          | no       | —       |             |
+
+</details>
 
 ## Generated documentation
 
@@ -43,6 +72,9 @@ export default defineParadoxConfig({
 
 ## Architecture preview
 
+<details>
+<summary>Architecture overview</summary>
+
 ```mermaid
 graph TD
   package__ankhorage_paradox["@ankhorage/paradox"]
@@ -212,6 +244,8 @@ graph TD
   module_src_write_write_ts --> module_src_render_types_ts
 ```
 
+</details>
+
 ## Path resolution
 
 - Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
@@ -223,21 +257,29 @@ graph TD
 
 ## Public API
 
-### defineParadoxConfig
+### Configuration
+
+<details>
+<summary>defineParadoxConfig</summary>
+
+```ts
+defineParadoxConfig(config: ParadoxConfig) => ParadoxConfig
+```
 
 Defines a Paradox configuration object without changing its shape.
 
-- Kind: `function`
-- Module: `src/config/defineParadoxConfig.ts`
-- Source: `src/config/defineParadoxConfig.ts:6:1`
-- Export paths: `src/index.ts`
-- Related symbols: `ParadoxConfig`
+Module: `src/config/defineParadoxConfig.ts`
+Source: `src/config/defineParadoxConfig.ts:8:1`
+Related symbols: `ParadoxConfig`
 
-### ParadoxConfig
+</details>
+
+<details>
+<summary>ParadoxConfig</summary>
 
 Configuration for running Paradox.
 
-- Kind: `type`
-- Module: `src/config/types.ts`
-- Source: `src/config/types.ts:6:1`
-- Export paths: `src/index.ts`
+Module: `src/config/types.ts`
+Source: `src/config/types.ts:7:1`
+
+</details>

package/dist/analyze/analyze.d.ts

@@ -1,8 +1,5 @@
 import type { ParadoxConfig } from '../config/types.js';
 import type { AnalysisResult } from './types.js';
-/***
- * Runs the source analysis pipeline for a configured package.
- */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;
 }): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -9,9 +9,6 @@ import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
 import { createUsageFromPackageJson } from './usage.js';
-/***
- * Runs the source analysis pipeline for a configured package.
- */
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
@@ -20,15 +17,9 @@ export async function analyze(config, runtime) {
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
     const program = createTypeScriptProgram({ root, entrypoints, project });
-    const { config: configMetadata, exports } = analyzeExports(project, {
-        root,
-        entrypoints,
-    });
+    const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
-    const modules = analyzeModules(project, {
-        root,
-        entrypoints,
-    });
+    const modules = analyzeModules(project, { root, entrypoints });
     const configExport = configMetadata
         ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
         : null;
@@ -63,6 +54,7 @@ export async function analyze(config, runtime) {
         config: configMetadata
             ? {
                 exportName: configMetadata.exportName,
+                isReadme: configMetadata.isReadme,
                 members: mapTypeMembers(configMembers),
             }
             : null,

package/dist/analyze/components.js

@@ -17,6 +17,7 @@ export function analyzeComponents(exports, options = {}) {
             name: member.name,
             type: member.type,
             required: member.required,
+            ...(member.defaultValue !== undefined ? { defaultValue: member.defaultValue } : {}),
             description: member.description ?? null,
         })) ?? [];
         const propsType = getComponentPropsType(e.node);
@@ -25,6 +26,8 @@ export function analyzeComponents(exports, options = {}) {
         components.push({
             name: e.name,
             description: e.description,
+            isReadme: e.isReadme,
+            examples: e.examples,
             modulePath: e.modulePath,
             sourceLocation: e.sourceLocation,
             exportPaths: e.exportPaths,

package/dist/analyze/exports.d.ts

@@ -4,6 +4,7 @@ interface AnalyzeExportsResult {
     exports: AnalysisExport[];
     config: {
         exportName: string;
+        isReadme: boolean;
     } | null;
 }
 /***

package/dist/analyze/exports.js

@@ -19,13 +19,12 @@ export function analyzeExports(project, options) {
                 continue;
             }
             const rawComment = getParadoxComment(decl);
-            const parsed = rawComment
-                ? parseParadoxComment(rawComment)
-                : { description: null, isConfig: false, params: {}, returns: null };
+            const parsed = rawComment ? parseParadoxComment(rawComment) : createEmptyMetadata();
             const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
                     exportName: name,
+                    isReadme: parsed.isReadme,
                 };
             }
             const metadata = getExportMetadata({
@@ -40,6 +39,8 @@ export function analyzeExports(project, options) {
                 ? {
                     ...existing,
                     description: existing.description ?? parsed.description,
+                    isReadme: existing.isReadme || parsed.isReadme,
+                    examples: existing.examples.length > 0 ? existing.examples : parsed.examples,
                     exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
                     relatedSymbols: uniqueSorted([
                         ...existing.relatedSymbols,
@@ -52,6 +53,8 @@ export function analyzeExports(project, options) {
                     name,
                     node: decl,
                     description: parsed.description,
+                    isReadme: parsed.isReadme,
+                    examples: parsed.examples,
                     kind: inferKind(decl),
                     ...metadata,
                 });
@@ -87,3 +90,13 @@ function uniqueSorted(values) {
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+function createEmptyMetadata() {
+    return {
+        description: null,
+        isConfig: false,
+        isReadme: false,
+        examples: [],
+        params: {},
+        returns: null,
+    };
+}

package/dist/analyze/types.d.ts

@@ -1,4 +1,9 @@
 import type { Node } from 'ts-morph';
+interface AnalysisExample {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 /***
  * Describes one exported declaration discovered in a package.
  */
@@ -33,6 +38,8 @@ export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
+    isReadme: boolean;
+    examples: AnalysisExample[];
     kind: 'function' | 'type' | 'unknown';
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
@@ -47,6 +54,8 @@ export interface AnalysisExport {
 export interface AnalysisComponent {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: AnalysisExample[];
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
     exportPaths: string[];
@@ -54,6 +63,7 @@ export interface AnalysisComponent {
         name: string;
         type: string;
         required: boolean;
+        defaultValue?: string;
         description: string | null;
     }[];
 }
@@ -129,6 +139,7 @@ export interface AnalysisResult {
     usage: AnalysisUsage | null;
     config: {
         exportName: string;
+        isReadme: boolean;
         members: AnalysisTypeMember[];
     } | null;
     graphs: AnalysisGraphs;

package/dist/analyze/utils/parseParadoxComment.d.ts

@@ -4,9 +4,16 @@
 interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
+    isReadme: boolean;
+    examples: ParsedExample[];
     params: Record<string, string>;
     returns: string | null;
 }
+interface ParsedExample {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 /***
  * Parses a Paradox doc comment into structured metadata.
  */

package/dist/analyze/utils/parseParadoxComment.js

@@ -2,20 +2,29 @@
  * Parses a Paradox doc comment into structured metadata.
  */
 export function parseParadoxComment(rawComment) {
-    const lines = rawComment
-        .replace(/^\/\*\*\*/, '')
-        .replace(/\*\/$/, '')
-        .split('\n')
-        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+    const lines = normalizeCommentLines(rawComment);
+    const descriptionLines = [];
+    const examples = [];
     let isConfig = false;
+    let isReadme = false;
     const params = {};
     let returns = null;
-    const description = lines
-        .filter((line) => {
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
         const trimmed = line.trimStart();
         if (trimmed.startsWith('@config')) {
             isConfig = true;
-            return false;
+            continue;
+        }
+        if (trimmed.startsWith('@readme')) {
+            isReadme = true;
+            continue;
+        }
+        if (trimmed.startsWith('@example')) {
+            const parsed = parseExample(lines, index);
+            examples.push(parsed.example);
+            index = parsed.nextIndex;
+            continue;
         }
         if (trimmed.startsWith('@param ')) {
             const paramBody = trimmed.slice('@param '.length).trim();
@@ -23,21 +32,59 @@ export function parseParadoxComment(rawComment) {
             if (name) {
                 params[name] = descriptionParts.join(' ').trim();
             }
-            return false;
+            continue;
         }
         if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
             const returnBody = trimmed.replace(/^@returns?/, '').trim();
             returns = returnBody.length > 0 ? returnBody : null;
-            return false;
+            continue;
         }
-        return true;
-    })
-        .join('\n')
-        .trim();
+        descriptionLines.push(line);
+    }
+    const description = descriptionLines.join('\n').trim();
     return {
         description: description.length > 0 ? description : null,
         isConfig,
+        isReadme,
+        examples,
         params,
         returns,
     };
 }
+function parseExample(lines, startIndex) {
+    const header = lines[startIndex]?.trimStart() ?? '';
+    const title = header.slice('@example'.length).trim();
+    let language = null;
+    const codeLines = [];
+    let index = startIndex + 1;
+    while (index < lines.length && (lines[index] ?? '').trim() === '') {
+        index += 1;
+    }
+    const firstCodeLine = lines[index]?.trim() ?? '';
+    if (firstCodeLine.startsWith('```')) {
+        language = firstCodeLine.slice('```'.length).trim() || null;
+        index += 1;
+        while (index < lines.length) {
+            const current = lines[index] ?? '';
+            if (current.trim() === '```')
+                break;
+            codeLines.push(current);
+            index += 1;
+        }
+    }
+    return {
+        example: {
+            title: title.length > 0 ? title : null,
+            language,
+            code: codeLines.join('\n').trimEnd(),
+        },
+        nextIndex: index,
+    };
+}
+function normalizeCommentLines(rawComment) {
+    return rawComment
+        .replace(/^\/\*\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+}

package/dist/config/defineParadoxConfig.d.ts

@@ -1,5 +1,7 @@
 import type { ParadoxConfig } from './types.js';
 /***
  * Defines a Paradox configuration object without changing its shape.
+ *
+ * @readme
  */
 export declare function defineParadoxConfig(config: ParadoxConfig): ParadoxConfig;

package/dist/config/defineParadoxConfig.js

@@ -1,5 +1,7 @@
 /***
  * Defines a Paradox configuration object without changing its shape.
+ *
+ * @readme
  */
 export function defineParadoxConfig(config) {
     return config;

package/dist/config/types.d.ts

@@ -2,6 +2,7 @@
  * Configuration for running Paradox.
  *
  * @config
+ * @readme
  */
 export interface ParadoxConfig {
     mode?: 'safe' | 'write';

package/dist/model/buildModel.d.ts

@@ -1,4 +1,9 @@
 import type { DocumentationModel, ExportKind } from './types.js';
+interface ExampleInput {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 interface ExportMemberInput {
     name: string;
     kind: 'property' | 'method';
@@ -31,6 +36,8 @@ interface BuildModelInput {
     exports: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         kind: ExportKind;
         modulePath: string;
         sourceLocation: {
@@ -56,6 +63,8 @@ interface BuildModelInput {
     components: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         modulePath: string;
         sourceLocation: {
             filePath: string;
@@ -67,6 +76,7 @@ interface BuildModelInput {
             name: string;
             type: string;
             required: boolean;
+            defaultValue?: string;
             description: string | null;
         }[];
     }[];
@@ -79,6 +89,7 @@ interface BuildModelInput {
     } | null;
     config: {
         exportName: string;
+        isReadme: boolean;
         members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];

package/dist/model/buildModel.js

@@ -27,6 +27,7 @@ export function buildModel(analysis) {
         config: analysis.config !== null
             ? {
                 exportName: analysis.config.exportName,
+                isReadme: analysis.config.isReadme,
                 configFile: getDefaultConfigFileName(analysis.packageId),
                 factoryName: findConfigFactoryName(analysis.config.exportName, [
                     ...exportsByName.keys(),
@@ -57,6 +58,8 @@ function mapExport(item, exportNames) {
     return {
         name: item.name,
         description: item.description,
+        isReadme: item.isReadme,
+        examples: item.examples.map((example) => ({ ...example })),
         kind: item.kind,
         modulePath: item.modulePath,
         sourceLocation: {
@@ -95,6 +98,8 @@ function mapComponent(component, exportModel) {
     return {
         name: component.name,
         description: component.description,
+        isReadme: component.isReadme,
+        examples: component.examples.map((example) => ({ ...example })),
         modulePath: component.modulePath,
         sourceLocation: {
             filePath: component.sourceLocation.filePath,
@@ -106,6 +111,7 @@ function mapComponent(component, exportModel) {
             name: prop.name,
             type: prop.type,
             required: prop.required,
+            defaultValue: prop.defaultValue,
             description: prop.description,
         }))),
     };

package/dist/model/types.d.ts

@@ -30,6 +30,7 @@ interface UsageCommandModel {
 }
 interface ConfigModel {
     exportName: string;
+    isReadme: boolean;
     configFile: string;
     factoryName: string | null;
     members: ConfigMemberModel[];
@@ -37,6 +38,8 @@ interface ConfigModel {
 export interface ExportModel {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: ExampleModel[];
     kind: ExportKind;
     modulePath: string;
     sourceLocation: SourceLocationModel;
@@ -49,11 +52,18 @@ export type ExportKind = 'function' | 'type' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: ExampleModel[];
     modulePath: string;
     sourceLocation: SourceLocationModel;
     exportPaths: string[];
     props: PropModel[];
 }
+interface ExampleModel {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 interface SourceLocationModel {
     filePath: string;
     line: number;
@@ -91,6 +101,7 @@ interface PropModel {
     name: string;
     type: string;
     required: boolean;
+    defaultValue?: string;
     description: string | null;
 }
 interface ConfigMemberModel {

package/dist/render/renderers/markdown.js

@@ -9,7 +9,13 @@ export function renderMarkdown({ badges, diagrams, model, outputDir, }) {
     };
 }
 function renderReadme(model, outputDir, badges, diagrams) {
-    const lines = [`# ${model.packageName}`, ''];
+    const lines = [
+        '<!-- markdownlint-disable MD013 MD033 -->',
+        '<!-- This file is generated by Paradox. Do not edit manually. -->',
+        '',
+        `# ${model.packageName}`,
+        '',
+    ];
     if (badges.length > 0) {
         lines.push(badges
             .map((badge) => `![${badgeLabel(model, badge.path)}](./${outputDir}/${badge.path})`)
@@ -19,45 +25,68 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push(model.description, '');
     }
     if (model.usage !== null) {
-        lines.push('## Usage', '');
+        lines.push('## Installation', '');
         lines.push('```bash');
         for (const command of model.usage.commands) {
             lines.push(command.command);
         }
         lines.push('```', '');
     }
+    renderDocumentationTags(lines);
+    if (model.config?.isReadme) {
+        renderConfiguration(lines, model);
+    }
+    renderGeneratedDocumentation(lines, outputDir, diagrams);
+    renderArchitecturePreview(lines, diagrams);
+    renderPathResolution(lines);
+    renderReadmeApi(lines, model);
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderDocumentationTags(lines) {
+    lines.push('## Documentation Tags', '');
+    for (const tag of DOCUMENTATION_TAGS) {
+        lines.push('<details>');
+        lines.push(`<summary>@${tag.name}</summary>`, '');
+        lines.push(tag.description, '');
+        lines.push('</details>', '');
+    }
+}
+function renderConfiguration(lines, model) {
     const { config } = model;
-    if (config !== null) {
-        lines.push('## Configuration', '');
-        lines.push(`Create a \`${config.configFile}\` file:`, '');
-        lines.push('```ts');
-        if (config.factoryName !== null) {
-            lines.push(`import { ${config.factoryName} } from '${model.packageId}';`);
-            lines.push('');
-            lines.push(`export default ${config.factoryName}({`);
-            lines.push('  // ...');
-            lines.push('});');
-        }
-        else {
-            lines.push(`import type { ${config.exportName} } from '${model.packageId}';`);
-            lines.push('');
-            lines.push('const config = {');
-            lines.push('  // ...');
-            lines.push(`} satisfies ${config.exportName};`);
-            lines.push('');
-            lines.push('export default config;');
-        }
-        lines.push('```', '');
-        if (config.members.length > 0) {
-            lines.push('### Configuration options', '');
-            lines.push('| Field | Type | Required | Default | Description |');
-            lines.push('| --- | --- | --- | --- | --- |');
-            for (const configMember of flattenConfigMembers(config.members)) {
-                lines.push(`| ${escapeTableCell(configMember.path)} | \`${escapeTableCell(configMember.type)}\` | ${configMember.required ? 'yes' : 'no'} | ${escapeTableCell(configMember.defaultValue ?? '')} | ${escapeTableCell(configMember.description ?? '')} |`);
-            }
-            lines.push('');
+    if (config === null)
+        return;
+    lines.push('## Configuration', '');
+    lines.push(`Create a \`${config.configFile}\` file:`, '');
+    lines.push('```ts');
+    if (config.factoryName !== null) {
+        lines.push(`import { ${config.factoryName} } from '${model.packageId}';`);
+        lines.push('');
+        lines.push(`export default ${config.factoryName}({`);
+        lines.push('  // ...');
+        lines.push('});');
+    }
+    else {
+        lines.push(`import type { ${config.exportName} } from '${model.packageId}';`);
+        lines.push('');
+        lines.push('const config = {');
+        lines.push('  // ...');
+        lines.push(`} satisfies ${config.exportName};`);
+        lines.push('');
+        lines.push('export default config;');
+    }
+    lines.push('```', '');
+    if (config.members.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Configuration options</summary>', '');
+        lines.push('| Field | Type | Required | Default | Description |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const configMember of flattenConfigMembers(config.members)) {
+            lines.push(`| ${escapeTableCell(configMember.path)} | \`${escapeTableCell(configMember.type)}\` | ${configMember.required ? 'yes' : 'no'} | ${renderDefault(configMember.defaultValue)} | ${escapeTableCell(configMember.description ?? '')} |`);
         }
+        lines.push('', '</details>', '');
     }
+}
+function renderGeneratedDocumentation(lines, outputDir, diagrams) {
     lines.push('## Generated documentation', '');
     lines.push(`- [Interactive documentation app](./${outputDir}/index.html)`);
     lines.push(`- [Public API reference](./${outputDir}/exports.md)`);
@@ -66,12 +95,19 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push(`- [${diagram.title}](./${outputDir}/${diagram.path})`);
     }
     lines.push('');
+}
+function renderArchitecturePreview(lines, diagrams) {
     lines.push('## Architecture preview', '');
     if (diagrams.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Architecture overview</summary>', '');
         lines.push('```mermaid');
-        lines.push(diagrams[0].content.trimEnd());
+        lines.push(diagrams[0]?.content.trimEnd() ?? '');
         lines.push('```', '');
+        lines.push('</details>', '');
     }
+}
+function renderPathResolution(lines) {
     lines.push('## Path resolution', '');
     lines.push('- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).');
     lines.push('- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.');
@@ -79,22 +115,131 @@ function renderReadme(model, outputDir, badges, diagrams) {
     lines.push('- Modes:');
     lines.push('  - `safe`: writes generated artifacts only under the output directory');
     lines.push('  - `write`: additionally updates `<packageRoot>/README.md`', '');
-    if (model.exports.length > 0) {
-        lines.push('## Public API', '');
-        for (const item of model.exports) {
-            lines.push(`### ${item.name}`, '');
-            lines.push(item.description ?? `\`${item.kind}\` export.`, '');
-            lines.push(`- Kind: \`${item.kind}\``);
-            lines.push(`- Module: \`${item.modulePath}\``);
-            lines.push(`- Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
-            lines.push(`- Export paths: ${item.exportPaths.map((path) => `\`${path}\``).join(', ')}`);
-            if (item.relatedSymbols.length > 0) {
-                lines.push(`- Related symbols: ${item.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`);
+}
+function renderReadmeApi(lines, model) {
+    const groups = getReadmeGroups(model);
+    if (groups.length === 0)
+        return;
+    lines.push('## Public API', '');
+    for (const group of groups) {
+        lines.push(`### ${group.title}`, '');
+        for (const item of group.items) {
+            if (item.kind === 'component') {
+                renderComponentAccordion(lines, item.component, item.exportEntry);
+            }
+            else {
+                renderExportAccordion(lines, item.exportEntry);
             }
-            lines.push('');
         }
     }
-    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderComponentAccordion(lines, component, exportEntry) {
+    lines.push('<details>');
+    lines.push(`<summary>${component.name}</summary>`, '');
+    renderSignature(lines, exportEntry);
+    if (component.description)
+        lines.push(component.description, '');
+    renderExamples(lines, component.examples);
+    if (exportEntry && exportEntry.relatedSymbols.length > 0) {
+        lines.push(`Related types: ${exportEntry.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`, '');
+    }
+    if (component.props.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Props</summary>', '');
+        lines.push('| Prop | Type | Required | Default | Description |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const prop of component.props) {
+            lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${renderDefault(prop.defaultValue)} | ${escapeTableCell(prop.description ?? '')} |`);
+        }
+        lines.push('', '</details>', '');
+    }
+    lines.push('</details>', '');
+}
+function renderExportAccordion(lines, item) {
+    lines.push('<details>');
+    lines.push(`<summary>${item.name}</summary>`, '');
+    renderSignature(lines, item);
+    lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+    renderExamples(lines, item.examples);
+    lines.push(`Module: \`${item.modulePath}\``);
+    lines.push(`Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
+    if (item.relatedSymbols.length > 0) {
+        lines.push(`Related symbols: ${item.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`);
+    }
+    lines.push('', '</details>', '');
+}
+function renderSignature(lines, item) {
+    const signature = item?.signatures[0]?.label;
+    if (!signature)
+        return;
+    lines.push('```ts');
+    lines.push(`${item.name}${signature}`);
+    lines.push('```', '');
+}
+function renderExamples(lines, examples) {
+    for (const example of examples) {
+        if (example.title)
+            lines.push(`#### ${example.title}`, '');
+        lines.push(`\`\`\`${example.language ?? ''}`);
+        lines.push(example.code);
+        lines.push('```', '');
+    }
+}
+function getReadmeGroups(model) {
+    const exportsByName = new Map(model.exports.map((entry) => [entry.name, entry]));
+    const componentNames = new Set(model.components.map((component) => component.name));
+    const groups = new Map();
+    for (const component of model.components.filter((entry) => entry.isReadme)) {
+        addReadmeItem(groups, getReadmeCategory(component.modulePath, component.name), {
+            kind: 'component',
+            component,
+            exportEntry: exportsByName.get(component.name),
+        });
+    }
+    for (const item of model.exports.filter((entry) => entry.isReadme)) {
+        if (componentNames.has(item.name))
+            continue;
+        addReadmeItem(groups, getReadmeCategory(item.modulePath, item.name), {
+            kind: 'export',
+            exportEntry: item,
+        });
+    }
+    return CATEGORY_ORDER.flatMap((title) => {
+        const items = groups.get(title);
+        if (!items || items.length === 0)
+            return [];
+        return [{ title, items: sortReadmeItems(items) }];
+    });
+}
+function addReadmeItem(groups, title, item) {
+    const existing = groups.get(title) ?? [];
+    existing.push(item);
+    groups.set(title, existing);
+}
+function sortReadmeItems(items) {
+    return [...items].sort((left, right) => getReadmeItemName(left).localeCompare(getReadmeItemName(right)));
+}
+function getReadmeItemName(item) {
+    return item.kind === 'component' ? item.component.name : item.exportEntry.name;
+}
+function getReadmeCategory(modulePath, name) {
+    if (modulePath.includes('/config/'))
+        return 'Configuration';
+    if (modulePath.includes('/primitives/'))
+        return 'Primitives';
+    if (modulePath.includes('/components/'))
+        return 'Components';
+    if (modulePath.includes('/patterns/'))
+        return 'Patterns';
+    if (modulePath.includes('/layout/'))
+        return 'Layout';
+    if (modulePath.includes('/hooks/') || /^use[A-Z]/.test(name))
+        return 'Hooks';
+    if (modulePath.includes('/utils/'))
+        return 'Utilities';
+    if (modulePath.endsWith('types.ts') || modulePath.includes('/types/'))
+        return 'Types';
+    return 'Utilities';
 }
 function renderExports(model) {
     const lines = ['# Public API', ''];
@@ -141,10 +286,10 @@ function renderComponents(model) {
             lines.push(`Export paths: ${component.exportPaths.map((path) => `\`${path}\``).join(', ')}`, '');
         }
         if (component.props.length > 0) {
-            lines.push('| Prop | Type | Required | Description |');
-            lines.push('| --- | --- | --- | --- |');
+            lines.push('| Prop | Type | Required | Default | Description |');
+            lines.push('| --- | --- | --- | --- | --- |');
             for (const prop of component.props) {
-                lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${escapeTableCell(prop.description ?? '')} |`);
+                lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${renderDefault(prop.defaultValue)} | ${escapeTableCell(prop.description ?? '')} |`);
             }
             lines.push('');
         }
@@ -154,6 +299,9 @@ function renderComponents(model) {
 function escapeTableCell(value) {
     return value.replaceAll('|', '\\|');
 }
+function renderDefault(value) {
+    return value === undefined ? '—' : `\`${escapeTableCell(value)}\``;
+}
 function flattenConfigMembers(members, prefix = '') {
     return members.flatMap((member) => {
         const path = prefix ? `${prefix}.${member.name}` : member.name;
@@ -177,3 +325,27 @@ function badgeLabel(model, badgePath) {
     const badge = model.badges.find((entry) => entry.id === id);
     return badge ? `${badge.label}: ${badge.value}` : badgePath;
 }
+const CATEGORY_ORDER = [
+    'Configuration',
+    'Primitives',
+    'Components',
+    'Patterns',
+    'Layout',
+    'Hooks',
+    'Utilities',
+    'Types',
+];
+const DOCUMENTATION_TAGS = [
+    {
+        name: 'readme',
+        description: 'Includes a documentation block or exported symbol in README output.',
+    },
+    {
+        name: 'config',
+        description: 'Marks a type or interface as part of the Paradox configuration model. `@config` alone does not imply README inclusion; use `@config` plus `@readme` for README output.',
+    },
+    {
+        name: 'example',
+        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
+    },
+];

package/package.json

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