@forge-ts/core 0.19.4 → 0.19.5

package/dist/index.d.ts

@@ -12,12 +12,14 @@ import { TSDocConfiguration } from '@microsoft/tsdoc';
 /**
  * Discriminated event types recorded in the audit trail.
  *
+ * @since 0.10.0
  * @public
  */
 type AuditEventType = "config.lock" | "config.unlock" | "config.drift" | "bypass.create" | "bypass.expire" | "rule.change";
 /**
  * A single audit event recorded in the forge-ts audit trail.
  *
+ * @since 0.10.0
  * @public
  */
 interface AuditEvent {
@@ -27,7 +29,10 @@ interface AuditEvent {
     event: AuditEventType;
     /** OS username of the actor (falls back to "unknown"). */
     user: string;
-    /** Mandatory for lock/unlock/bypass events; optional otherwise. */
+    /**
+     * Mandatory for lock/unlock/bypass events; optional otherwise.
+     * @defaultValue undefined
+     */
     reason?: string;
     /** Event-specific payload. */
     details: Record<string, unknown>;
@@ -47,6 +52,7 @@ declare function getCurrentUser(): string;
 /**
  * Appends a single audit event to the `.forge-audit.jsonl` file.
  *
+ * @remarks
  * Creates the file if it does not exist. The file is strictly append-only —
  * existing content is never modified or truncated.
  *
@@ -55,33 +61,37 @@ declare function getCurrentUser(): string;
  * @example
  * ```typescript
  * import { appendAuditEvent } from "@forge-ts/core";
- * appendAuditEvent("/path/to/project", {
- *   timestamp: new Date().toISOString(),
- *   event: "config.lock",
- *   user: "alice",
- *   reason: "Stabilize v2 config",
- *   details: { hash: "abc123" },
- * });
+ * const event = { timestamp: new Date().toISOString(), event: "config.lock" as const, user: "alice", reason: "Stabilize", details: {} };
+ * appendAuditEvent("/path/to/project", event);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function appendAuditEvent(rootDir: string, event: AuditEvent): void;
 /**
  * Options for reading the audit log.
  *
+ * @since 0.10.0
  * @public
  */
 interface ReadAuditOptions {
-    /** Maximum number of events to return. */
+    /**
+     * Maximum number of events to return.
+     * @defaultValue undefined
+     */
     limit?: number;
-    /** Filter to a single event type. */
+    /**
+     * Filter to a single event type.
+     * @defaultValue undefined
+     */
     eventType?: AuditEventType;
 }
 /**
  * Reads the `.forge-audit.jsonl` file and returns parsed audit events.
  *
+ * @remarks
  * Returns newest events first. If the file does not exist, returns an empty
- * array.
+ * array. Invalid JSON lines are silently skipped.
  *
  * @param rootDir - Absolute path to the project root directory.
  * @param options - Optional limit and event type filter.
@@ -92,27 +102,27 @@ interface ReadAuditOptions {
  * const events = readAuditLog("/path/to/project", { limit: 10 });
  * console.log(events.length); // up to 10
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function readAuditLog(rootDir: string, options?: ReadAuditOptions): AuditEvent[];
 /**
  * Formats a single audit event as a human-readable string.
  *
+ * @remarks
+ * Produces a single-line representation suitable for terminal output or
+ * log files. Includes the timestamp, event type, user, reason, and details.
+ *
  * @param event - The audit event to format.
  * @returns A single-line human-readable representation.
  * @example
  * ```typescript
  * import { formatAuditEvent } from "@forge-ts/core";
- * const line = formatAuditEvent({
- *   timestamp: "2026-03-21T12:00:00.000Z",
- *   event: "config.lock",
- *   user: "alice",
- *   reason: "Stabilize v2 config",
- *   details: { hash: "abc123" },
- * });
+ * const event = { timestamp: "2026-03-21T12:00:00.000Z", event: "config.lock" as const, user: "alice", reason: "Stabilize", details: {} };
+ * const line = formatAuditEvent(event);
  * console.log(line);
- * // "[2026-03-21T12:00:00.000Z] config.lock by alice — Stabilize v2 config  {hash: abc123}"
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function formatAuditEvent(event: AuditEvent): string;
@@ -133,6 +143,7 @@ declare function formatAuditEvent(event: AuditEvent): string;
 /**
  * Configuration for the bypass budget system.
  *
+ * @since 0.10.0
  * @public
  */
 interface BypassConfig {
@@ -144,6 +155,7 @@ interface BypassConfig {
 /**
  * A single bypass record stored in `.forge-bypass.json`.
  *
+ * @since 0.10.0
  * @public
  */
 interface BypassRecord {
@@ -164,7 +176,9 @@ interface BypassRecord {
  * Creates a new bypass record, writes it to `.forge-bypass.json`, and appends
  * an audit event.
  *
- * Throws an error if the daily budget is exhausted.
+ * @remarks
+ * Throws an error if the daily budget is exhausted. Each bypass is recorded
+ * in the audit trail for governance traceability.
  *
  * @param rootDir - Absolute path to the project root directory.
  * @param reason - Mandatory justification for the bypass.
@@ -175,15 +189,20 @@ interface BypassRecord {
  * @example
  * ```typescript
  * import { createBypass } from "@forge-ts/core";
- * const bypass = createBypass("/path/to/project", "hotfix for release", "E009");
- * console.log(bypass.id); // unique bypass ID
+ * const bypass = createBypass("/path/to/project", "hotfix for release", "E009", { dailyBudget: 5, durationHours: 12 });
+ * console.log(bypass.id);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function createBypass(rootDir: string, reason: string, rule?: string, config?: Partial<BypassConfig>): BypassRecord;
 /**
  * Returns all currently active (non-expired) bypass records.
  *
+ * @remarks
+ * Filters bypass records by comparing their `expiresAt` timestamp against
+ * the current time. Expired records are not removed by this function.
+ *
  * @param rootDir - Absolute path to the project root directory.
  * @returns Array of active bypass records.
  * @example
@@ -192,12 +211,14 @@ declare function createBypass(rootDir: string, reason: string, rule?: string, co
  * const active = getActiveBypasses("/path/to/project");
  * console.log(`${active.length} active bypass(es)`);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function getActiveBypasses(rootDir: string): BypassRecord[];
 /**
  * Checks whether a specific rule has an active bypass.
  *
+ * @remarks
  * A rule is considered bypassed if there is an active bypass with the exact
  * rule code or an "all" bypass.
  *
@@ -211,13 +232,16 @@ declare function getActiveBypasses(rootDir: string): BypassRecord[];
  *   console.log("E009 is currently bypassed");
  * }
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function isRuleBypassed(rootDir: string, ruleCode: string): boolean;
 /**
  * Returns the number of bypass budget slots remaining for today.
  *
+ * @remarks
  * Counts bypasses created today (UTC) against the configured daily budget.
+ * When no config override is provided, the default budget of 3 is used.
  *
  * @param rootDir - Absolute path to the project root directory.
  * @param config - Optional bypass budget configuration overrides.
@@ -225,16 +249,19 @@ declare function isRuleBypassed(rootDir: string, ruleCode: string): boolean;
  * @example
  * ```typescript
  * import { getRemainingBudget } from "@forge-ts/core";
- * const remaining = getRemainingBudget("/path/to/project");
+ * const remaining = getRemainingBudget("/path/to/project", { dailyBudget: 5, durationHours: 24 });
  * console.log(`${remaining} bypass(es) remaining today`);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function getRemainingBudget(rootDir: string, config?: Partial<BypassConfig>): number;
 /**
  * Removes expired bypass records from `.forge-bypass.json`.
  *
+ * @remarks
  * Also appends a `bypass.expire` audit event for each expired record removed.
+ * Returns 0 without writing the file when no records have expired.
  *
  * @param rootDir - Absolute path to the project root directory.
  * @returns The number of expired records removed.
@@ -244,13 +271,15 @@ declare function getRemainingBudget(rootDir: string, config?: Partial<BypassConf
  * const removed = expireOldBypasses("/path/to/project");
  * console.log(`${removed} expired bypass(es) removed`);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function expireOldBypasses(rootDir: string): number;
 
 /**
  * Visibility levels for exported symbols.
- * Derived from TSDoc release tags (@public, @beta, @internal).
+ * Derived from TSDoc release tags (`@public`, `@beta`, `@internal`).
+ * @since 0.1.0
  * @public
  */
 declare enum Visibility {
@@ -261,6 +290,7 @@ declare enum Visibility {
 }
 /**
  * A single extracted and annotated symbol from the TypeScript AST.
+ * @since 0.1.0
  * @public
  */
 interface ForgeSymbol {
@@ -276,7 +306,10 @@ interface ForgeSymbol {
     line: number;
     /** 0-based column of the declaration. */
     column: number;
-    /** Parsed TSDoc documentation, if present. */
+    /**
+     * Parsed TSDoc documentation, if present.
+     * @defaultValue undefined
+     */
     documentation?: {
         summary?: string;
         params?: Array<{
@@ -312,9 +345,15 @@ interface ForgeSymbol {
             line: number;
         }>;
     };
-    /** Human-readable type signature of the symbol. */
+    /**
+     * Human-readable type signature of the symbol.
+     * @defaultValue undefined
+     */
     signature?: string;
-    /** Child symbols (e.g., class members, enum values). */
+    /**
+     * Child symbols (e.g., class members, enum values).
+     * @defaultValue undefined
+     */
     children?: ForgeSymbol[];
     /** Whether this symbol is part of the public module exports. */
     exported: boolean;
@@ -324,24 +363,26 @@ interface ForgeSymbol {
  * - `"error"` — violation fails the build.
  * - `"warn"`  — violation is reported but does not fail the build.
  * - `"off"`   — rule is disabled entirely.
+ * @since 0.1.0
  * @public
  */
 type RuleSeverity = "error" | "warn" | "off";
 /**
  * Per-rule severity configuration for the TSDoc enforcer.
  * Each key corresponds to one of the E001–E007 rule codes.
+ * @since 0.1.0
  * @public
  */
 interface EnforceRules {
     /** E001: Exported symbol missing TSDoc summary. */
     "require-summary": RuleSeverity;
-    /** E002: Function parameter missing @param tag. */
+    /** E002: Function parameter missing `\@param` tag. */
     "require-param": RuleSeverity;
-    /** E003: Non-void function missing @returns tag. */
+    /** E003: Non-void function missing `\@returns` tag. */
     "require-returns": RuleSeverity;
-    /** E004: Exported function missing @example block. */
+    /** E004: Exported function missing `\@example` block. */
     "require-example": RuleSeverity;
-    /** E005: Entry point missing @packageDocumentation. */
+    /** E005: Entry point missing `\@packageDocumentation`. */
     "require-package-doc": RuleSeverity;
     /** E006: Class member missing documentation. */
     "require-class-member-doc": RuleSeverity;
@@ -349,42 +390,43 @@ interface EnforceRules {
     "require-interface-member-doc": RuleSeverity;
     /** W006: TSDoc syntax parse error (invalid tag, malformed block, etc.). */
     "require-tsdoc-syntax": RuleSeverity;
-    /** E013: Exported function/class is missing a @remarks block. */
+    /** E013: Exported function/class is missing a `\@remarks` block. */
     "require-remarks": RuleSeverity;
-    /** E014: Optional property with default is missing @defaultValue. */
+    /** E014: Optional property with default is missing `\@defaultValue`. */
     "require-default-value": RuleSeverity;
-    /** E015: Generic symbol is missing @typeParam for its type parameters. */
+    /** E015: Generic symbol is missing `\@typeParam` for its type parameters. */
     "require-type-param": RuleSeverity;
-    /** W005: Symbol references other symbols via {@link} but has no @see tags. */
+    /** W005: Symbol references other symbols via `\@link` but has no `\@see` tags. */
     "require-see": RuleSeverity;
-    /** E016: Exported symbol is missing a release tag (@public, @beta, @internal). */
+    /** E016: Exported symbol is missing a release tag (`\@public`, `\@beta`, `\@internal`). */
     "require-release-tag": RuleSeverity;
     /** W007: Guide FORGE:AUTO section references a symbol that no longer exists or has changed. */
     "require-fresh-guides": RuleSeverity;
     /** W008: Exported public symbol is not mentioned in any guide page. */
     "require-guide-coverage": RuleSeverity;
-    /** E017: @internal symbol re-exported through public barrel (index.ts). */
+    /** E017: `\@internal` symbol re-exported through public barrel (index.ts). */
     "require-internal-boundary": RuleSeverity;
-    /** E018: @route-tagged function missing @response tag. */
+    /** E018: `\@route`-tagged function missing `\@response` tag. */
     "require-route-response": RuleSeverity;
-    /** W009: {@inheritDoc} references a symbol that does not exist. */
+    /** W009: `\@inheritDoc` references a symbol that does not exist. */
     "require-inheritdoc-source": RuleSeverity;
-    /** W010: @breaking without @migration path. */
+    /** W010: `\@breaking` without `\@migration` path. */
     "require-migration-path": RuleSeverity;
-    /** W011: New public export missing @since version tag. */
+    /** W011: New public export missing `\@since` version tag. */
     "require-since": RuleSeverity;
-    /** W013: @example block may be stale — function call arg count mismatches parameter count. */
+    /** W013: `\@example` block may be stale — function call arg count mismatches parameter count. */
     "require-fresh-examples": RuleSeverity;
     /** E019: Non-test file contains ts-ignore or ts-expect-error directive. */
     "require-no-ts-ignore": RuleSeverity;
     /** E020: Exported symbol has `any` in its public API signature. */
     "require-no-any-in-api": RuleSeverity;
-    /** W012: {@link} display text appears stale relative to target summary. */
+    /** W012: `\@link` display text appears stale relative to target summary. */
     "require-fresh-link-text": RuleSeverity;
 }
 /**
  * Full configuration for a forge-ts run.
  * Loaded from forge-ts.config.ts or the "forge-ts" key in package.json.
+ * @since 0.1.0
  * @public
  */
 interface ForgeConfig {
@@ -542,6 +584,7 @@ interface ForgeConfig {
     /**
      * Warnings generated during config loading (e.g., unknown keys).
      * Populated by loadConfig(). Agents should surface these in output.
+     * @defaultValue undefined
      * @internal
      */
     _configWarnings?: string[];
@@ -567,6 +610,7 @@ interface ForgeConfig {
 }
 /**
  * The result of a forge-ts compilation pass.
+ * @since 0.1.0
  * @public
  */
 interface ForgeResult {
@@ -580,11 +624,15 @@ interface ForgeResult {
     warnings: ForgeWarning[];
     /** Wall-clock duration of the run in milliseconds. */
     duration: number;
-    /** Absolute paths of files written during this run (populated by gen). */
+    /**
+     * Absolute paths of files written during this run (populated by gen).
+     * @defaultValue undefined
+     */
     writtenFiles?: string[];
 }
 /**
  * A diagnostic error produced during a forge-ts run.
+ * @since 0.1.0
  * @public
  */
 interface ForgeError {
@@ -598,15 +646,25 @@ interface ForgeError {
     line: number;
     /** 0-based column. */
     column: number;
-    /** Suggested fix for the agent — exact TSDoc block to add. */
+    /**
+     * Suggested fix for the agent — exact TSDoc block to add.
+     * @defaultValue undefined
+     */
     suggestedFix?: string;
-    /** The symbol name that needs fixing. */
+    /**
+     * The symbol name that needs fixing.
+     * @defaultValue undefined
+     */
     symbolName?: string;
-    /** The symbol kind (function, class, interface, etc.). */
+    /**
+     * The symbol kind (function, class, interface, etc.).
+     * @defaultValue undefined
+     */
     symbolKind?: string;
 }
 /**
  * A diagnostic warning produced during a forge-ts run.
+ * @since 0.1.0
  * @public
  */
 interface ForgeWarning {
@@ -630,12 +688,15 @@ interface ForgeWarning {
  * - **discretionary**: Release-tag family (`@public`, `@beta`, `@internal`).
  * - Rules not listed here are **guard rules** and are not affected by group settings.
  *
+ * @see {@link EnforceRules}
+ * @since 0.1.0
  * @public
  */
 declare const RULE_GROUP_MAP: Partial<Record<keyof EnforceRules, "core" | "extended" | "discretionary">>;
 /**
  * Type-safe helper for defining a partial forge-ts configuration.
  *
+ * @remarks
  * Only include the settings you want to override — everything else
  * inherits sensible defaults via `loadConfig()`.
  *
@@ -645,46 +706,55 @@ declare const RULE_GROUP_MAP: Partial<Record<keyof EnforceRules, "core" | "exten
  * ```typescript
  * import { defineConfig } from "@forge-ts/core";
  *
- * export default defineConfig({
- *   outDir: "docs",
- *   enforce: { strict: true },
- *   gen: { ssgTarget: "mintlify" },
- * });
+ * const config = { outDir: "docs", enforce: { strict: true } };
+ * export default defineConfig(config);
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function defineConfig(config: Partial<ForgeConfig>): Partial<ForgeConfig>;
 /**
  * Constructs a sensible default {@link ForgeConfig} rooted at `rootDir`.
  *
+ * @remarks
+ * All configuration fields receive production-ready defaults. The returned
+ * object is fully populated and can be used without any further merging.
+ *
  * @param rootDir - Absolute path to the project root.
  * @returns A fully-populated default configuration.
+ * @see {@link ForgeConfig}
+ * @see {@link loadConfig}
  * @example
  * ```typescript
  * import { defaultConfig } from "@forge-ts/core";
  * const config = defaultConfig("/path/to/project");
  * console.log(config.enforce.enabled); // true
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function defaultConfig(rootDir: string): ForgeConfig;
 /**
  * Loads the forge-ts configuration for a project.
  *
+ * @remarks
  * Resolution order:
- * 1. `<rootDir>/forge-ts.config.ts`
- * 2. `<rootDir>/forge-ts.config.js`
- * 3. `"forge-ts"` key inside `<rootDir>/package.json`
+ * 1. `\<rootDir\>/forge-ts.config.ts`
+ * 2. `\<rootDir\>/forge-ts.config.js`
+ * 3. `"forge-ts"` key inside `\<rootDir\>/package.json`
  * 4. Built-in defaults (returned when none of the above is found)
  *
  * @param rootDir - The project root to search for config.  Defaults to `process.cwd()`.
  * @returns A fully-resolved {@link ForgeConfig}.
+ * @see {@link ForgeConfig}
+ * @see {@link defaultConfig}
  * @example
  * ```typescript
  * import { loadConfig } from "@forge-ts/core";
  * const config = await loadConfig("/path/to/project");
  * // config is fully resolved with defaults
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function loadConfig(rootDir?: string): Promise<ForgeConfig>;
@@ -704,6 +774,7 @@ declare function loadConfig(rootDir?: string): Promise<ForgeConfig>;
  * Captures a point-in-time snapshot of the project's forge-ts configuration
  * so that future runs can detect when settings have been weakened.
  *
+ * @since 0.10.0
  * @public
  */
 interface ForgeLockManifest {
@@ -726,6 +797,7 @@ interface ForgeLockManifest {
 /**
  * A single violation found when comparing current config against the lock.
  *
+ * @since 0.10.0
  * @public
  */
 interface LockViolation {
@@ -741,6 +813,10 @@ interface LockViolation {
 /**
  * Reads the `.forge-lock.json` file from the given project root.
  *
+ * @remarks
+ * Returns `null` when the file does not exist or contains invalid JSON,
+ * so callers can safely use a null check to determine lock state.
+ *
  * @param rootDir - Absolute path to the project root.
  * @returns The parsed lock manifest, or `null` if no lock file exists or is invalid.
  * @example
@@ -751,27 +827,39 @@ interface LockViolation {
  *   console.log(`Locked at ${lock.lockedAt} by ${lock.lockedBy}`);
  * }
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function readLockFile(rootDir: string): ForgeLockManifest | null;
 /**
  * Writes a {@link ForgeLockManifest} to `.forge-lock.json` in the project root.
  *
+ * @remarks
+ * Overwrites any existing lock file. The manifest is serialised as
+ * pretty-printed JSON with a trailing newline.
+ *
  * @param rootDir - Absolute path to the project root.
  * @param manifest - The lock manifest to write.
+ * @see {@link ForgeLockManifest}
+ * @see {@link createLockManifest}
  * @example
  * ```typescript
  * import { writeLockFile, createLockManifest, loadConfig } from "@forge-ts/core";
  * const config = await loadConfig("/path/to/project");
- * const manifest = createLockManifest(config);
+ * const manifest = createLockManifest(config, "alice");
  * writeLockFile("/path/to/project", manifest);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function writeLockFile(rootDir: string, manifest: ForgeLockManifest): void;
 /**
  * Removes the `.forge-lock.json` file from the project root.
  *
+ * @remarks
+ * Safe to call even when no lock file exists — returns `false` in that case
+ * rather than throwing.
+ *
  * @param rootDir - Absolute path to the project root.
  * @returns `true` if the file existed and was removed, `false` otherwise.
  * @example
@@ -780,31 +868,37 @@ declare function writeLockFile(rootDir: string, manifest: ForgeLockManifest): vo
  * const removed = removeLockFile("/path/to/project");
  * console.log(removed ? "Lock removed" : "No lock file found");
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function removeLockFile(rootDir: string): boolean;
 /**
  * Creates a {@link ForgeLockManifest} from the current project config.
  *
+ * @remarks
  * Snapshots the enforce rule severities and guard settings so they can
  * be compared on future runs to detect weakening.
  *
  * @param config - The fully-resolved {@link ForgeConfig} to snapshot.
  * @param lockedBy - Identifier of the user or agent creating the lock. Defaults to `"forge-ts lock"`.
  * @returns A new lock manifest ready to be written with {@link writeLockFile}.
+ * @see {@link ForgeLockManifest}
+ * @see {@link writeLockFile}
  * @example
  * ```typescript
  * import { createLockManifest, loadConfig } from "@forge-ts/core";
  * const config = await loadConfig();
- * const manifest = createLockManifest(config);
- * console.log(manifest.config.rules); // { "require-summary": "error", ... }
+ * const manifest = createLockManifest(config, "alice");
+ * console.log(manifest.config.rules);
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function createLockManifest(config: ForgeConfig, lockedBy?: string): ForgeLockManifest;
 /**
  * Validates the current config against a locked manifest.
  *
+ * @remarks
  * Returns an array of violations where the current config has weakened
  * settings relative to the locked state. Weakening means:
  * - A rule severity changed from `"error"` to `"warn"` or `"off"`
@@ -817,6 +911,8 @@ declare function createLockManifest(config: ForgeConfig, lockedBy?: string): For
  * @param config - The current fully-resolved {@link ForgeConfig}.
  * @param lock - The lock manifest to validate against.
  * @returns An array of {@link LockViolation} entries. Empty means no weakening detected.
+ * @see {@link LockViolation}
+ * @see {@link ForgeLockManifest}
  * @example
  * ```typescript
  * import { validateAgainstLock, readLockFile, loadConfig } from "@forge-ts/core";
@@ -829,6 +925,7 @@ declare function createLockManifest(config: ForgeConfig, lockedBy?: string): For
  *   }
  * }
  * ```
+ * @since 0.10.0
  * @public
  */
 declare function validateAgainstLock(config: ForgeConfig, lock: ForgeLockManifest): LockViolation[];
@@ -844,42 +941,89 @@ declare function validateAgainstLock(config: ForgeConfig, lock: ForgeLockManifes
  */
 /**
  * OpenAPI 3.2 schema object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPISchemaObject {
-    /** The data type of the schema (e.g., "string", "number", "object", "array"). */
+    /**
+     * The data type of the schema (e.g., "string", "number", "object", "array").
+     * @defaultValue undefined
+     */
     type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
-    /** A format hint for the data type (e.g., "int32", "date-time", "email", "uuid"). */
+    /**
+     * A format hint for the data type (e.g., "int32", "date-time", "email", "uuid").
+     * @defaultValue undefined
+     */
     format?: string;
-    /** A human-readable description of the schema's purpose or constraints. */
+    /**
+     * A human-readable description of the schema's purpose or constraints.
+     * @defaultValue undefined
+     */
     description?: string;
-    /** Property definitions for object-type schemas. Maps each property name to its schema. */
+    /**
+     * Property definitions for object-type schemas. Maps each property name to its schema.
+     * @defaultValue undefined
+     */
     properties?: Record<string, OpenAPISchemaObject>;
-    /** List of property names that must be present on the object. */
+    /**
+     * List of property names that must be present on the object.
+     * @defaultValue undefined
+     */
     required?: string[];
-    /** Schema definition for the elements of an array-type schema. Required when `type` is "array". */
+    /**
+     * Schema definition for the elements of an array-type schema. Required when `type` is "array".
+     * @defaultValue undefined
+     */
     items?: OpenAPISchemaObject;
-    /** Controls whether additional properties are allowed (`true`/`false`) or defines their schema. */
+    /**
+     * Controls whether additional properties are allowed (`true`/`false`) or defines their schema.
+     * @defaultValue undefined
+     */
     additionalProperties?: boolean | OpenAPISchemaObject;
-    /** Restricts the value to one of the listed constants. */
+    /**
+     * Restricts the value to one of the listed constants.
+     * @defaultValue undefined
+     */
     enum?: Array<string | number | boolean>;
-    /** Validates the value against exactly one of the listed sub-schemas. */
+    /**
+     * Validates the value against exactly one of the listed sub-schemas.
+     * @defaultValue undefined
+     */
     oneOf?: OpenAPISchemaObject[];
-    /** Validates the value against all of the listed sub-schemas (intersection). */
+    /**
+     * Validates the value against all of the listed sub-schemas (intersection).
+     * @defaultValue undefined
+     */
     allOf?: OpenAPISchemaObject[];
-    /** Validates the value against at least one of the listed sub-schemas. */
+    /**
+     * Validates the value against at least one of the listed sub-schemas.
+     * @defaultValue undefined
+     */
     anyOf?: OpenAPISchemaObject[];
-    /** Indicates that the value may be `null` in addition to its declared type. */
+    /**
+     * Indicates that the value may be `null` in addition to its declared type.
+     * @defaultValue undefined
+     */
     nullable?: boolean;
-    /** Marks the schema as deprecated, signalling that it may be removed in a future version. */
+    /**
+     * Marks the schema as deprecated, signalling that it may be removed in a future version.
+     * @defaultValue undefined
+     */
     deprecated?: boolean;
-    /** The default value to use when the property is absent. */
+    /**
+     * The default value to use when the property is absent.
+     * @defaultValue undefined
+     */
     default?: string | number | boolean | null;
-    /** A JSON Reference (`$ref`) pointing to another schema definition in the document. */
+    /**
+     * A JSON Reference (`$ref`) pointing to another schema definition in the document.
+     * @defaultValue undefined
+     */
     $ref?: string;
 }
 /**
  * OpenAPI 3.2 info object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIInfoObject {
@@ -887,11 +1031,20 @@ interface OpenAPIInfoObject {
     title: string;
     /** The version string for the API (e.g., "1.0.0"). */
     version: string;
-    /** A detailed description of the API, supporting CommonMark markdown. */
+    /**
+     * A detailed description of the API, supporting CommonMark markdown.
+     * @defaultValue undefined
+     */
     description?: string;
-    /** A short summary of the API, intended for display in tooling. */
+    /**
+     * A short summary of the API, intended for display in tooling.
+     * @defaultValue undefined
+     */
     summary?: string;
-    /** Licensing information for the exposed API, including name, URL, and SPDX identifier. */
+    /**
+     * Licensing information for the exposed API, including name, URL, and SPDX identifier.
+     * @defaultValue undefined
+     */
     license?: {
         name: string;
         url?: string;
@@ -900,64 +1053,125 @@ interface OpenAPIInfoObject {
 }
 /**
  * OpenAPI 3.2 tag object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPITagObject {
     /** The name of the tag, used to group operations in the document. */
     name: string;
-    /** An optional description of the tag, supporting CommonMark markdown. */
+    /**
+     * An optional description of the tag, supporting CommonMark markdown.
+     * @defaultValue undefined
+     */
     description?: string;
 }
 /**
  * OpenAPI 3.2 path item object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIPathItemObject {
-    /** A short summary of the path item, intended for tooling display. */
+    /**
+     * A short summary of the path item, intended for tooling display.
+     * @defaultValue undefined
+     */
     summary?: string;
-    /** A detailed description of the path item, supporting CommonMark markdown. */
+    /**
+     * A detailed description of the path item, supporting CommonMark markdown.
+     * @defaultValue undefined
+     */
     description?: string;
-    /** The operation definition for HTTP GET requests to this path. */
+    /**
+     * The operation definition for HTTP GET requests to this path.
+     * @defaultValue undefined
+     */
     get?: OpenAPIOperationObject;
-    /** The operation definition for HTTP POST requests to this path. */
+    /**
+     * The operation definition for HTTP POST requests to this path.
+     * @defaultValue undefined
+     */
     post?: OpenAPIOperationObject;
-    /** The operation definition for HTTP PUT requests to this path. */
+    /**
+     * The operation definition for HTTP PUT requests to this path.
+     * @defaultValue undefined
+     */
     put?: OpenAPIOperationObject;
-    /** The operation definition for HTTP DELETE requests to this path. */
+    /**
+     * The operation definition for HTTP DELETE requests to this path.
+     * @defaultValue undefined
+     */
     delete?: OpenAPIOperationObject;
-    /** The operation definition for HTTP PATCH requests to this path. */
+    /**
+     * The operation definition for HTTP PATCH requests to this path.
+     * @defaultValue undefined
+     */
     patch?: OpenAPIOperationObject;
-    /** The operation definition for HTTP OPTIONS requests to this path. */
+    /**
+     * The operation definition for HTTP OPTIONS requests to this path.
+     * @defaultValue undefined
+     */
     options?: OpenAPIOperationObject;
-    /** The operation definition for HTTP HEAD requests to this path. */
+    /**
+     * The operation definition for HTTP HEAD requests to this path.
+     * @defaultValue undefined
+     */
     head?: OpenAPIOperationObject;
-    /** The operation definition for HTTP TRACE requests to this path. */
+    /**
+     * The operation definition for HTTP TRACE requests to this path.
+     * @defaultValue undefined
+     */
     trace?: OpenAPIOperationObject;
-    /** The operation definition for HTTP QUERY requests to this path (OpenAPI 3.2 extension). */
+    /**
+     * The operation definition for HTTP QUERY requests to this path (OpenAPI 3.2 extension).
+     * @defaultValue undefined
+     */
     query?: OpenAPIOperationObject;
-    /** Additional non-standard HTTP method operations keyed by method name. */
+    /**
+     * Additional non-standard HTTP method operations keyed by method name.
+     * @defaultValue undefined
+     */
     additionalOperations?: Record<string, OpenAPIOperationObject>;
 }
 /**
  * OpenAPI 3.2 operation object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIOperationObject {
-    /** A unique string identifier for the operation, used by tooling to reference it. */
+    /**
+     * A unique string identifier for the operation, used by tooling to reference it.
+     * @defaultValue undefined
+     */
     operationId?: string;
-    /** A short, human-readable summary of what the operation does. */
+    /**
+     * A short, human-readable summary of what the operation does.
+     * @defaultValue undefined
+     */
     summary?: string;
-    /** A detailed description of the operation's behaviour, supporting CommonMark markdown. */
+    /**
+     * A detailed description of the operation's behaviour, supporting CommonMark markdown.
+     * @defaultValue undefined
+     */
     description?: string;
-    /** A list of tag names that logically group this operation in documentation and tooling. */
+    /**
+     * A list of tag names that logically group this operation in documentation and tooling.
+     * @defaultValue undefined
+     */
     tags?: string[];
-    /** The list of parameters applicable to this operation. */
+    /**
+     * The list of parameters applicable to this operation.
+     * @defaultValue undefined
+     */
     parameters?: OpenAPIParameterObject[];
-    /** The possible responses returned by this operation, keyed by HTTP status code or "default". */
+    /**
+     * The possible responses returned by this operation, keyed by HTTP status code or "default".
+     * @defaultValue undefined
+     */
     responses?: Record<string, OpenAPIResponseObject>;
 }
 /**
  * OpenAPI 3.2 parameter object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIParameterObject {
@@ -965,98 +1179,151 @@ interface OpenAPIParameterObject {
     name: string;
     /** The location of the parameter: path, query, header, cookie, or querystring. */
     in: "query" | "header" | "path" | "cookie" | "querystring";
-    /** A human-readable description of the parameter's purpose, supporting CommonMark markdown. */
+    /**
+     * A human-readable description of the parameter's purpose, supporting CommonMark markdown.
+     * @defaultValue undefined
+     */
     description?: string;
-    /** Whether the parameter is mandatory. Required for `in: "path"` parameters. */
+    /**
+     * Whether the parameter is mandatory. Required for `in: "path"` parameters.
+     * @defaultValue undefined
+     */
     required?: boolean;
-    /** The schema defining the type and constraints of the parameter value. */
+    /**
+     * The schema defining the type and constraints of the parameter value.
+     * @defaultValue undefined
+     */
     schema?: OpenAPISchemaObject;
-    /** Marks the parameter as deprecated; clients should avoid using it. */
+    /**
+     * Marks the parameter as deprecated; clients should avoid using it.
+     * @defaultValue undefined
+     */
     deprecated?: boolean;
 }
 /**
  * OpenAPI 3.2 encoding object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIEncodingObject {
-    /** The MIME type to use for encoding a specific property (e.g., "application/json"). */
+    /**
+     * The MIME type to use for encoding a specific property (e.g., "application/json").
+     * @defaultValue undefined
+     */
     contentType?: string;
-    /** Additional headers to send alongside the encoded part, keyed by header name. */
+    /**
+     * Additional headers to send alongside the encoded part, keyed by header name.
+     * @defaultValue undefined
+     */
     headers?: Record<string, OpenAPIParameterObject>;
-    /** The serialization style for the encoded value (e.g., "form", "spaceDelimited"). */
+    /**
+     * The serialization style for the encoded value (e.g., "form", "spaceDelimited").
+     * @defaultValue undefined
+     */
     style?: string;
-    /** Whether arrays and objects should be exploded into separate query parameters. */
+    /**
+     * Whether arrays and objects should be exploded into separate query parameters.
+     * @defaultValue undefined
+     */
     explode?: boolean;
-    /** Whether reserved characters in the encoded value should be allowed without percent-encoding. */
+    /**
+     * Whether reserved characters in the encoded value should be allowed without percent-encoding.
+     * @defaultValue undefined
+     */
     allowReserved?: boolean;
 }
 /**
  * OpenAPI 3.2 media type object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIMediaTypeObject {
-    /** The schema defining the structure and type of the media type's payload. */
+    /**
+     * The schema defining the structure and type of the media type's payload.
+     * @defaultValue undefined
+     */
     schema?: OpenAPISchemaObject;
-    /** Encoding information for specific properties of a `multipart` or `application/x-www-form-urlencoded` request body. */
+    /**
+     * Encoding information for specific properties of a `multipart` or `application/x-www-form-urlencoded` request body.
+     * @defaultValue undefined
+     */
     encoding?: Record<string, OpenAPIEncodingObject>;
 }
 /**
  * OpenAPI 3.2 response object.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIResponseObject {
     /** A required human-readable description of the response, supporting CommonMark markdown. */
     description: string;
-    /** HTTP headers returned with this response, keyed by header name. */
+    /**
+     * HTTP headers returned with this response, keyed by header name.
+     * @defaultValue undefined
+     */
     headers?: Record<string, OpenAPIParameterObject>;
-    /** The response body content, keyed by media type (e.g., "application/json"). */
+    /**
+     * The response body content, keyed by media type (e.g., "application/json").
+     * @defaultValue undefined
+     */
     content?: Record<string, OpenAPIMediaTypeObject>;
 }
 /**
  * Complete OpenAPI 3.2 document.
+ * @since 0.1.0
  * @public
  */
 interface OpenAPIDocument {
     /** The OpenAPI specification version this document conforms to. Must be "3.2.0". */
     openapi: "3.2.0";
-    /** An optional self-referencing URL for this document, used for tooling and resolution. */
+    /**
+     * An optional self-referencing URL for this document, used for tooling and resolution.
+     * @defaultValue undefined
+     */
     $self?: string;
     /** Metadata about the API including title, version, and description. */
     info: OpenAPIInfoObject;
-    /** The available paths and their operations, keyed by path template (e.g., "/users/{id}"). */
+    /** The available paths and their operations, keyed by path template (e.g., `/users/\{id\}`). */
     paths: Record<string, OpenAPIPathItemObject>;
     /** Reusable schema and media type definitions shared across the document. */
     components: {
         schemas: Record<string, OpenAPISchemaObject>;
         mediaTypes?: Record<string, OpenAPIMediaTypeObject>;
     };
-    /** A list of tags used to group operations, with optional descriptions. */
+    /**
+     * A list of tags used to group operations, with optional descriptions.
+     * @defaultValue undefined
+     */
     tags?: OpenAPITagObject[];
 }
 
 /**
  * Determines the visibility level of a symbol from its TSDoc release tags.
  *
+ * @remarks
  * The precedence order is:
- * 1. `@internal`  → {@link Visibility.Internal}
- * 2. `@beta`      → {@link Visibility.Beta}
- * 3. `@public`    → {@link Visibility.Public}
+ * 1. `\@internal`  → {@link Visibility.Internal}
+ * 2. `\@beta`      → {@link Visibility.Beta}
+ * 3. `\@public`    → {@link Visibility.Public}
  * 4. (no tag)     → {@link Visibility.Public} (default for exports)
  *
  * @param tags - The parsed `tags` map from `ForgeSymbol.documentation`.
  * @returns The resolved {@link Visibility} value.
+ * @see {@link Visibility}
  * @example
  * ```typescript
  * import { resolveVisibility } from "@forge-ts/core";
  * const vis = resolveVisibility({ internal: [] });
  * // vis === Visibility.Internal
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function resolveVisibility(tags: Record<string, string[]> | undefined): Visibility;
 /**
  * Returns whether `candidate` meets or exceeds the required minimum visibility.
  *
+ * @remarks
  * "Meets" means the symbol is at least as visible as `minVisibility`.
  * For example, `Public` meets a minimum of `Public`, but `Internal` does not.
  *
@@ -1066,6 +1333,7 @@ declare function resolveVisibility(tags: Record<string, string[]> | undefined):
  * @param candidate - The visibility of the symbol being tested.
  * @param minVisibility - The minimum visibility threshold.
  * @returns `true` if `candidate` is at least as visible as `minVisibility`.
+ * @see {@link Visibility}
  * @example
  * ```typescript
  * import { meetsVisibility, Visibility } from "@forge-ts/core";
@@ -1073,6 +1341,7 @@ declare function resolveVisibility(tags: Record<string, string[]> | undefined):
  * meetsVisibility(Visibility.Internal, Visibility.Public); // false
  * meetsVisibility("public", "beta"); // true (string literals also accepted)
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function meetsVisibility(candidate: Visibility | "public" | "beta" | "internal" | "private", minVisibility: Visibility | "public" | "beta" | "internal" | "private"): boolean;
@@ -1080,14 +1349,20 @@ declare function meetsVisibility(candidate: Visibility | "public" | "beta" | "in
  * Filters an array of {@link ForgeSymbol} objects to only include symbols
  * whose visibility meets or exceeds `minVisibility`.
  *
+ * @remarks
+ * Returns a new array — the original is not modified.
+ *
  * @param symbols - The full list of symbols to filter.
  * @param minVisibility - The minimum visibility threshold to keep.
  * @returns A new array containing only symbols that pass the visibility check.
+ * @see {@link meetsVisibility}
+ * @see {@link ForgeSymbol}
  * @example
  * ```typescript
  * import { filterByVisibility, Visibility } from "@forge-ts/core";
  * const publicOnly = filterByVisibility(symbols, Visibility.Public);
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function filterByVisibility(symbols: ForgeSymbol[], minVisibility: Visibility | "public" | "beta" | "internal" | "private"): ForgeSymbol[];
@@ -1113,6 +1388,8 @@ declare function clearTSDocConfigCache(): void;
 declare function loadTSDocConfiguration(folderPath: string): TSDocConfiguration;
 /**
  * The return type of {@link createWalker}.
+ * @see {@link createWalker}
+ * @since 0.1.0
  * @public
  */
 interface ASTWalker {
@@ -1125,6 +1402,7 @@ interface ASTWalker {
 /**
  * Creates an {@link ASTWalker} configured for the given forge config.
  *
+ * @remarks
  * The walker uses the TypeScript Compiler API to create a `ts.Program` from
  * the project's tsconfig, then visits every source file to extract exported
  * declarations.  TSDoc comments are parsed with `@microsoft/tsdoc` to
@@ -1132,6 +1410,9 @@ interface ASTWalker {
  *
  * @param config - The resolved {@link ForgeConfig} for the project.
  * @returns An {@link ASTWalker} instance whose `walk()` method performs the extraction.
+ * @see {@link ASTWalker}
+ * @see {@link ForgeConfig}
+ * @see {@link ForgeSymbol}
  * @example
  * ```typescript
  * import { loadConfig, createWalker } from "@forge-ts/core";
@@ -1140,6 +1421,7 @@ interface ASTWalker {
  * const symbols = walker.walk();
  * console.log(`Found ${symbols.length} symbols`);
  * ```
+ * @since 0.1.0
  * @public
  */
 declare function createWalker(config: ForgeConfig): ASTWalker;