@ankhorage/paradox 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.6
+
+### Patch Changes
+
+- 8ba8f5c: Remove the hardcoded Path resolution section from generated README output so consumer documentation only contains analyzed package content.
+
+## 0.1.5
+
+### Patch Changes
+
+- fd606af: Move documentation tag metadata into a typed registry, stop rendering Paradox tag docs by default in consumer READMEs, and add structured table rendering for documented const array exports.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![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)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.5](./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.
 
@@ -64,29 +64,6 @@ sequenceDiagram
 
 </details>
 
-## 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:
@@ -119,6 +96,7 @@ export default defineParadoxConfig({
 - [Architecture overview](./paradox/diagrams/architecture-overview.mmd)
 - [Module relationships](./paradox/diagrams/module-relationships.mmd)
 - [Export graph](./paradox/diagrams/export-graph.mmd)
+- [isParadoxDocTagName sequence](./paradox/diagrams/sequences/is-paradox-doc-tag-name.mmd)
 - [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
 
 ## Architecture preview
@@ -267,6 +245,8 @@ graph TD
   module_src_config_defineParadoxConfig_ts --> module_src_config_types_ts
   module_src_config_types_ts["src/config/types.ts"]
   package__ankhorage_paradox -.-> module_src_config_types_ts
+  module_src_doc_tags_registry_ts["src/doc-tags/registry.ts"]
+  package__ankhorage_paradox -.-> module_src_doc_tags_registry_ts
   module_src_index_ts["src/index.ts"]
   module_src_model_buildModel_ts["src/model/buildModel.ts"]
   package__ankhorage_paradox -.-> module_src_model_buildModel_ts
@@ -311,15 +291,6 @@ graph TD
 
 </details>
 
-## Path resolution
-
-- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
-- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.
-- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.
-- Modes:
-  - `safe`: writes generated artifacts only under the output directory
-  - `write`: additionally updates `<packageRoot>/README.md`
-
 ## Public API
 
 ### Config
@@ -348,3 +319,23 @@ Module: `src/config/types.ts`
 Source: `src/config/types.ts:7:1`
 
 </details>
+
+### Documentation
+
+<details>
+<summary>PARADOX_DOC_TAGS</summary>
+
+Supported Paradox documentation tags.
+
+Paradox supports doc tags inside triple-star documentation comments.
+
+| name      | syntax     | description                                                                                                                                                      | applies to      | repeatable | handler        |
+| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------- | -------------- |
+| `readme`  | `@readme`  | Includes a documentation block or exported symbol in README output.                                                                                              | block, symbol   | no         | `markReadme`   |
+| `config`  | `@config`  | 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. | interface, type | no         | `markConfig`   |
+| `example` | `@example` | Adds a titled fenced code example to the generated documentation for a symbol.                                                                                   | symbol          | yes        | `parseExample` |
+
+Module: `src/doc-tags/registry.ts`
+Source: `src/doc-tags/registry.ts:8:14`
+
+</details>

package/dist/analyze/exports.d.ts

@@ -1,4 +1,4 @@
-import type { Project } from 'ts-morph';
+import { type Project } from 'ts-morph';
 import type { AnalysisExport } from './types.js';
 interface AnalyzeExportsResult {
     exports: AnalysisExport[];

package/dist/analyze/exports.js

@@ -1,4 +1,5 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
+import { Node } from 'ts-morph';
 import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -48,6 +49,9 @@ export function analyzeExports(project, options) {
                     ]),
                     signatures: existing.signatures.length > 0 ? existing.signatures : metadata.signatures,
                     members: existing.members.length > 0 ? existing.members : metadata.members,
+                    structuredRows: existing.structuredRows.length > 0
+                        ? existing.structuredRows
+                        : metadata.structuredRows,
                 }
                 : {
                     name,
@@ -65,6 +69,9 @@ export function analyzeExports(project, options) {
         config,
     };
 }
+/***
+ * Resolves configured entrypoint paths to source files in the TypeScript project.
+ */
 function getEntryPointSourceFiles(project, options) {
     return options.entrypoints
         .map((entrypoint) => {
@@ -73,23 +80,40 @@ function getEntryPointSourceFiles(project, options) {
     })
         .filter((sourceFile) => sourceFile != null);
 }
+/***
+ * Returns the first declaration for a symbol, or null when none exists.
+ */
 function getFirstDeclaration(declarations) {
     const [declaration = null] = declarations;
     return declaration;
 }
+/***
+ * Infers the public export kind from the declaration shape.
+ */
 function inferKind(node) {
     if ('getParameters' in node)
         return 'function';
     if ('getProperties' in node || 'getMembers' in node)
         return 'type';
+    if (Node.isVariableDeclaration(node))
+        return 'value';
     return 'unknown';
 }
+/***
+ * 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('\\', '/');
 }
+/***
+ * Creates empty documentation metadata for exports without Paradox comments.
+ */
 function createEmptyMetadata() {
     return {
         description: null,

package/dist/analyze/types.d.ts

@@ -34,19 +34,23 @@ export interface AnalysisMember {
     inheritedFrom?: string;
     children?: AnalysisMember[];
 }
+export interface AnalysisStructuredRow {
+    values: Record<string, string>;
+}
 export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
     isReadme: boolean;
     examples: AnalysisExample[];
-    kind: 'function' | 'type' | 'unknown';
+    kind: 'function' | 'type' | 'value' | 'unknown';
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
     exportPaths: string[];
     relatedSymbols: string[];
     signatures: AnalysisSignature[];
     members: AnalysisMember[];
+    structuredRows: AnalysisStructuredRow[];
 }
 /***
  * Describes one React component and its extracted props.

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

@@ -9,4 +9,4 @@ export declare function getExportMetadata(options: {
     root: string;
     entrypointPath: string;
     symbol: MorphSymbol;
-}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation'>;
+}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation' | 'structuredRows'>;

package/dist/analyze/utils/getExportMetadata.js

@@ -10,6 +10,7 @@ export function getExportMetadata(options) {
     const sourceLocation = getSourceLocation(options.node, options.root);
     const signatures = getSignatures(options.symbol, options.node);
     const members = getMembers(options.node);
+    const structuredRows = getStructuredRows(options.node, options.name);
     const relatedSymbols = collectRelatedSymbols(options.name, signatures.flatMap((signature) => [
         ...signature.parameters.map((parameter) => parameter.type),
         signature.returnType,
@@ -21,8 +22,12 @@ export function getExportMetadata(options) {
         relatedSymbols,
         signatures,
         members,
+        structuredRows,
     };
 }
+/***
+ * Resolves the source location for a declaration relative to the package root.
+ */
 function getSourceLocation(node, root) {
     const sourceFile = node.getSourceFile();
     const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
@@ -32,6 +37,9 @@ function getSourceLocation(node, root) {
         column,
     };
 }
+/***
+ * Extracts callable signatures for exported functions and callable values.
+ */
 function getSignatures(symbol, node) {
     const parsed = readParadoxMetadata(node);
     const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns));
@@ -39,6 +47,9 @@ function getSignatures(symbol, node) {
         signature.returnType !== null ||
         signature.returnDescription !== null), (signature) => signature.label);
 }
+/***
+ * Builds one normalized call signature from a callable declaration.
+ */
 function getSignature(declaration, params, returns) {
     const normalizedParameters = declaration.getParameters().map((parameter) => {
         const parameterDescription = params[parameter.getName()];
@@ -60,6 +71,9 @@ function getSignature(declaration, params, returns) {
         returnDescription: returns,
     };
 }
+/***
+ * Extracts members for interface and type literal exports.
+ */
 function getMembers(node) {
     if (getCallableNode(node) !== null)
         return [];
@@ -74,6 +88,9 @@ function getMembers(node) {
     }
     return [];
 }
+/***
+ * Converts TypeScript properties into documented member metadata.
+ */
 function getMembersFromProperties(properties) {
     return properties.flatMap((property) => {
         const declaration = getFirstDeclaration(property.getDeclarations());
@@ -83,7 +100,14 @@ function getMembersFromProperties(properties) {
         const rawComment = getParadoxComment(declaration);
         const parsed = rawComment
             ? parseParadoxComment(rawComment)
-            : { description: null, isConfig: false, params: {}, returns: null };
+            : {
+                description: null,
+                isConfig: false,
+                isReadme: false,
+                examples: [],
+                params: {},
+                returns: null,
+            };
         return [
             {
                 name: property.getName(),
@@ -95,10 +119,102 @@ function getMembersFromProperties(properties) {
         ];
     });
 }
+/***
+ * Extracts table-like rows from exported const arrays of object literals.
+ */
+function getStructuredRows(node, exportName) {
+    const declaration = getVariableDeclaration(node, exportName);
+    if (declaration === null)
+        return [];
+    const initializer = getStructuredArrayLiteral(declaration.getInitializer());
+    if (initializer === null)
+        return [];
+    return initializer.getElements().flatMap((element) => {
+        if (!Node.isObjectLiteralExpression(element))
+            return [];
+        const values = getObjectLiteralValues(element);
+        return Object.keys(values).length > 0 ? [{ values }] : [];
+    });
+}
+/***
+ * Resolves const assertions and returns the array literal used for structured docs.
+ */
+function getStructuredArrayLiteral(node) {
+    if (node === undefined)
+        return null;
+    if (Node.isArrayLiteralExpression(node))
+        return node;
+    if (Node.isAsExpression(node))
+        return getStructuredArrayLiteral(node.getExpression());
+    return null;
+}
+/***
+ * Resolves a variable declaration from declaration nodes used by export symbols.
+ */
+function getVariableDeclaration(node, exportName) {
+    if (Node.isVariableDeclaration(node))
+        return node;
+    if (Node.isVariableStatement(node)) {
+        return (node
+            .getDeclarationList()
+            .getDeclarations()
+            .find((declaration) => declaration.getName() === exportName) ?? null);
+    }
+    if (Node.isVariableDeclarationList(node)) {
+        return (node.getDeclarations().find((declaration) => declaration.getName() === exportName) ?? null);
+    }
+    return null;
+}
+/***
+ * Extracts primitive and string-array values from one object literal.
+ */
+function getObjectLiteralValues(node) {
+    const values = {};
+    for (const property of node.getProperties()) {
+        if (!Node.isPropertyAssignment(property))
+            continue;
+        const name = property.getName().replace(/^['"]|['"]$/g, '');
+        const value = getLiteralValue(property.getInitializer());
+        if (value !== null) {
+            values[name] = value;
+        }
+    }
+    return values;
+}
+/***
+ * Converts supported literal expressions into displayable string values.
+ */
+function getLiteralValue(node) {
+    if (node === undefined)
+        return null;
+    if (Node.isStringLiteral(node))
+        return node.getLiteralText();
+    if (Node.isNoSubstitutionTemplateLiteral(node))
+        return node.getLiteralText();
+    if (node.getKindName() === 'TrueKeyword')
+        return 'true';
+    if (node.getKindName() === 'FalseKeyword')
+        return 'false';
+    if (Node.isNumericLiteral(node))
+        return node.getText();
+    if (Node.isArrayLiteralExpression(node)) {
+        const values = node.getElements().map((element) => getLiteralValue(element));
+        if (values.some((value) => value === null))
+            return null;
+        return values.join(', ');
+    }
+    return null;
+}
+/***
+ * Returns the first declaration for a symbol, or null when none exists.
+ */
 function getFirstDeclaration(declarations) {
     const [declaration = null] = declarations;
     return declaration;
 }
+/***
+ * Finds callable declarations associated with an export symbol.
+ */
 function getCallableDeclarations(symbol, node) {
     const declarations = symbol
         .getDeclarations()
@@ -110,6 +226,9 @@ function getCallableDeclarations(symbol, node) {
     const callableNode = getCallableNode(node);
     return callableNode !== null ? [callableNode] : [];
 }
+/***
+ * Returns the callable node represented by a declaration when one exists.
+ */
 function getCallableNode(node) {
     if (Node.isFunctionDeclaration(node))
         return node;
@@ -130,15 +249,31 @@ function getCallableNode(node) {
     }
     return null;
 }
+/***
+ * Checks whether a node is a method declaration or method signature.
+ */
 function isMemberMethodDeclaration(node) {
     return Node.isMethodDeclaration(node) || Node.isMethodSignature(node);
 }
+/***
+ * Reads Paradox comment metadata from a declaration.
+ */
 function readParadoxMetadata(node) {
     const rawComment = getParadoxComment(node);
     return rawComment
         ? parseParadoxComment(rawComment)
-        : { description: null, isConfig: false, params: {}, returns: null };
+        : {
+            description: null,
+            isConfig: false,
+            isReadme: false,
+            examples: [],
+            params: {},
+            returns: null,
+        };
 }
+/***
+ * Finds related exported symbols mentioned in signature and member type text.
+ */
 function collectRelatedSymbols(exportName, ...values) {
     const candidates = values.flatMap((entries) => entries).filter((entry) => entry !== null);
     const related = new Set();
@@ -152,9 +287,15 @@ function collectRelatedSymbols(exportName, ...values) {
     }
     return [...related].sort((left, right) => left.localeCompare(right));
 }
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+/***
+ * Returns unique items by a caller-provided key while preserving first occurrence order.
+ */
 function uniqueBy(items, key) {
     const seen = new Set();
     return items.filter((item) => {

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

@@ -1,5 +1,5 @@
-import type { Node } from 'ts-morph';
+import { type Node as MorphNode } from 'ts-morph';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
-export declare function getParadoxComment(node: Node | undefined): string | null;
+export declare function getParadoxComment(node: MorphNode | undefined): string | null;

package/dist/analyze/utils/getParadoxComment.js

@@ -1,3 +1,4 @@
+import { Node } from 'ts-morph';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
@@ -6,7 +7,31 @@ export function getParadoxComment(node) {
         return null;
     const sourceFile = node.getSourceFile();
     const text = sourceFile.getFullText();
-    const nodeStart = node.getStart(false);
+    for (const nodeStart of getCommentTargetStarts(node)) {
+        const comment = readCommentBefore(text, nodeStart);
+        if (comment !== null)
+            return comment;
+    }
+    return null;
+}
+/***
+ * Returns declaration positions that may own a leading Paradox comment.
+ */
+function getCommentTargetStarts(node) {
+    const starts = [node.getStart(false)];
+    if (Node.isVariableDeclaration(node)) {
+        const parent = node.getParent();
+        const statement = Node.isVariableDeclarationList(parent) ? parent.getParent() : undefined;
+        if (statement !== undefined && Node.isVariableStatement(statement)) {
+            starts.unshift(statement.getStart(false));
+        }
+    }
+    return starts;
+}
+/***
+ * Reads a Paradox doc comment directly before a target position.
+ */
+function readCommentBefore(text, nodeStart) {
     const beforeNode = text.slice(0, nodeStart);
     const commentStart = beforeNode.lastIndexOf('/***');
     if (commentStart === -1)

package/dist/doc-tags/registry.d.ts

@@ -0,0 +1,39 @@
+/***
+ * Supported Paradox documentation tags.
+ *
+ * Paradox supports doc tags inside triple-star documentation comments.
+ *
+ * @readme
+ */
+export declare const PARADOX_DOC_TAGS: readonly [{
+    readonly name: "readme";
+    readonly syntax: "@readme";
+    readonly description: "Includes a documentation block or exported symbol in README output.";
+    readonly appliesTo: readonly ["block", "symbol"];
+    readonly repeatable: false;
+    readonly handler: "markReadme";
+}, {
+    readonly name: "config";
+    readonly syntax: "@config";
+    readonly 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.";
+    readonly appliesTo: readonly ["interface", "type"];
+    readonly repeatable: false;
+    readonly handler: "markConfig";
+}, {
+    readonly name: "example";
+    readonly syntax: "@example";
+    readonly description: "Adds a titled fenced code example to the generated documentation for a symbol.";
+    readonly appliesTo: readonly ["symbol"];
+    readonly repeatable: true;
+    readonly handler: "parseExample";
+}];
+export type ParadoxDocTagName = (typeof PARADOX_DOC_TAGS)[number]['name'];
+export type ParadoxDocTagHandlerId = (typeof PARADOX_DOC_TAGS)[number]['handler'];
+/***
+ * Looks up documentation tag metadata by tag name.
+ */
+export declare function getParadoxDocTag(name: string): (typeof PARADOX_DOC_TAGS)[number] | null;
+/***
+ * Checks whether a string is a supported Paradox documentation tag name.
+ */
+export declare function isParadoxDocTagName(name: string): name is ParadoxDocTagName;

package/dist/doc-tags/registry.js

@@ -0,0 +1,45 @@
+/***
+ * Supported Paradox documentation tags.
+ *
+ * Paradox supports doc tags inside triple-star documentation comments.
+ *
+ * @readme
+ */
+export const PARADOX_DOC_TAGS = [
+    {
+        name: 'readme',
+        syntax: '@readme',
+        description: 'Includes a documentation block or exported symbol in README output.',
+        appliesTo: ['block', 'symbol'],
+        repeatable: false,
+        handler: 'markReadme',
+    },
+    {
+        name: 'config',
+        syntax: '@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.',
+        appliesTo: ['interface', 'type'],
+        repeatable: false,
+        handler: 'markConfig',
+    },
+    {
+        name: 'example',
+        syntax: '@example',
+        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
+        appliesTo: ['symbol'],
+        repeatable: true,
+        handler: 'parseExample',
+    },
+];
+/***
+ * Looks up documentation tag metadata by tag name.
+ */
+export function getParadoxDocTag(name) {
+    return PARADOX_DOC_TAGS.find((tag) => tag.name === name) ?? null;
+}
+/***
+ * Checks whether a string is a supported Paradox documentation tag name.
+ */
+export function isParadoxDocTagName(name) {
+    return getParadoxDocTag(name) !== null;
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
 export type { ParadoxConfig } from './config/types.js';
+export type { ParadoxDocTagHandlerId, ParadoxDocTagName } from './doc-tags/registry.js';
+export { getParadoxDocTag, isParadoxDocTagName, PARADOX_DOC_TAGS } from './doc-tags/registry.js';

package/dist/index.js

@@ -1 +1,2 @@
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
+export { getParadoxDocTag, isParadoxDocTagName, PARADOX_DOC_TAGS } from './doc-tags/registry.js';

package/dist/model/buildModel.d.ts

@@ -59,6 +59,9 @@ interface BuildModelInput {
             returnDescription: string | null;
         }[];
         members: ExportMemberInput[];
+        structuredRows: {
+            values: Record<string, string>;
+        }[];
     }[];
     components: {
         name: string;

package/dist/model/buildModel.js

@@ -112,6 +112,7 @@ function mapExport(item, exportNames) {
             inheritedFrom: member.inheritedFrom,
             children: member.children,
         }))),
+        structuredRows: item.structuredRows.map((row) => ({ values: { ...row.values } })),
     };
 }
 /***

package/dist/model/types.d.ts

@@ -49,8 +49,9 @@ export interface ExportModel {
     relatedSymbols: string[];
     signatures: SignatureModel[];
     members: MemberModel[];
+    structuredRows: StructuredRowModel[];
 }
-export type ExportKind = 'function' | 'type' | 'unknown';
+export type ExportKind = 'function' | 'type' | 'value' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
@@ -106,6 +107,9 @@ interface MemberModel {
     inheritedFrom?: string;
     children?: MemberModel[];
 }
+interface StructuredRowModel {
+    values: Record<string, string>;
+}
 export interface ModuleModel {
     path: string;
     isEntrypoint: boolean;

package/dist/render/renderers/markdown.js

@@ -33,13 +33,11 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push('```', '');
     }
     renderCliScenarios(lines, model, outputDir, diagrams);
-    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`;
 }
@@ -73,15 +71,6 @@ function renderCliScenarios(lines, model, outputDir, diagrams) {
 function findScenarioDiagram(diagrams, scenario) {
     return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
 }
-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)
@@ -138,15 +127,6 @@ function renderArchitecturePreview(lines, diagrams) {
         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.');
-    lines.push('- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.');
-    lines.push('- Modes:');
-    lines.push('  - `safe`: writes generated artifacts only under the output directory');
-    lines.push('  - `write`: additionally updates `<packageRoot>/README.md`', '');
-}
 function renderReadmeApi(lines, model) {
     const groups = getReadmeGroups(model);
     if (groups.length === 0)
@@ -191,6 +171,7 @@ function renderExportAccordion(lines, item) {
     lines.push(`<summary>${item.name}</summary>`, '');
     renderSignature(lines, item);
     lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+    renderStructuredRows(lines, item);
     renderExamples(lines, item.examples);
     lines.push(`Module: \`${item.modulePath}\``);
     lines.push(`Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
@@ -216,6 +197,46 @@ function renderExamples(lines, examples) {
         lines.push('```', '');
     }
 }
+function renderStructuredRows(lines, item) {
+    if (item.structuredRows.length === 0)
+        return;
+    const columns = getStructuredColumns(item);
+    if (columns.length === 0)
+        return;
+    lines.push('| ' + columns.map(formatStructuredColumnHeader).join(' | ') + ' |');
+    lines.push('| ' + columns.map(() => '---').join(' | ') + ' |');
+    for (const row of item.structuredRows) {
+        lines.push('| ' +
+            columns
+                .map((column) => formatStructuredCell(column, row.values[column] ?? ''))
+                .join(' | ') +
+            ' |');
+    }
+    lines.push('');
+}
+function getStructuredColumns(item) {
+    const columns = new Set();
+    for (const row of item.structuredRows) {
+        for (const column of Object.keys(row.values)) {
+            columns.add(column);
+        }
+    }
+    return [...columns];
+}
+function formatStructuredColumnHeader(column) {
+    return escapeTableCell(column.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase());
+}
+function formatStructuredCell(column, value) {
+    const escaped = escapeTableCell(value);
+    if (column === 'syntax' || column === 'name' || column === 'handler') {
+        return `\`${escaped}\``;
+    }
+    if (value === 'true')
+        return 'yes';
+    if (value === 'false')
+        return 'no';
+    return escaped;
+}
 function getReadmeGroups(model) {
     const exportsByName = new Map(model.exports.map((entry) => [entry.name, entry]));
     const componentNames = new Set(model.components.map((component) => component.name));
@@ -256,6 +277,8 @@ function getReadmeItemName(item) {
 function getReadmeCategory(modulePath, name) {
     if (modulePath.includes('/config/'))
         return 'Config';
+    if (modulePath.includes('/doc-tags/'))
+        return 'Documentation';
     if (modulePath.includes('/primitives/'))
         return 'Primitives';
     if (modulePath.includes('/components/'))
@@ -282,6 +305,7 @@ function renderExports(model) {
         if (item.description) {
             lines.push(item.description, '');
         }
+        renderStructuredRows(lines, item);
         if (item.signatures.length > 0) {
             lines.push('### Signatures', '');
             for (const signature of item.signatures) {
@@ -365,6 +389,7 @@ function toFileStem(value) {
 }
 const CATEGORY_ORDER = [
     'Config',
+    'Documentation',
     'Primitives',
     'Components',
     'Patterns',
@@ -373,17 +398,3 @@ const CATEGORY_ORDER = [
     '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.1.4",
+  "version": "0.1.6",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {