@gandalan/weblibs 1.5.28 → 1.5.30

package/JSDOC.md

@@ -1,390 +1,159 @@
-# JSDoc Reference for WebLibs
+# JSDoc Guide for WebLibs
 
-This document records the JSDoc stabilization work done in `WebLibs` and defines the rules that must be followed going forward.
+This guide explains the small set of rules that keep IntelliSense working for consumers of `@gandalan/weblibs`.
 
-The goal is simple:
+Use it when you add:
 
-- No API member should degrade to `any` because of broken JSDoc.
-- No DTO type should degrade to `any` because of missing exports, missing imports, or non-module files.
-- Type information must stay discoverable in VS Code IntelliSense through `import("...").Type` and local typedef aliases.
+- DTO properties
+- API methods
+- root function exports
+- classes or other public types
 
+If you follow the patterns below, consumers get stable types in both JS and TS.
 
-## What Was Changed
 
-The following classes of problems were fixed.
+## Goal
 
-### 1. API typedef exports were completed
+Public types must stay discoverable from:
 
-Several business API files did not export a stable API type alias, or exported it inconsistently.
+- `import("@gandalan/weblibs").TypeName`
+- `import { someFunction } from "@gandalan/weblibs"`
+- generated `index.d.ts`
 
-The working pattern is:
+The package relies on JSDoc as the source of truth, and `npm run generate:dts` builds the root declaration output.
 
-```js
-/**
- * @typedef {ReturnType<typeof createProduktionApi>} ProduktionApi
- */
-```
 
-This pattern was added or standardized for affected business API files.
+## The Short Version
 
+1. Every pure-type JS file must be an ES module.
+2. Always use `.js` in JSDoc import paths.
+3. Import cross-file DTO types locally.
+4. In API files, define short local typedef aliases at the top.
+5. Avoid circular typing like `@returns {XApi}` together with `@typedef {ReturnType<typeof createXApi>} XApi`.
+6. Regenerate declarations after public type changes.
 
-### 2. Circular API typing was removed
 
-Some API factory functions used this pattern:
+## Basic Rules
 
-```js
-/**
- * @returns {ProduktionApi}
- */
-export function createProduktionApi(fluentApi) {
-```
+### 1. Make type-only files real modules
 
-while the same file also defined:
-
-```js
-/**
- * @typedef {ReturnType<typeof createProduktionApi>} ProduktionApi
- */
-```
-
-That is circular. The JS language service can collapse this to `any`.
-
-The `@returns {XApi}` annotation was removed from those files when `XApi` was defined via `ReturnType<typeof createXApi>`.
-
-
-### 3. `idasFluentApi` member typing was stabilized
-
-`IDASFluentApi` was normalized so that business members are typed consistently through imported API aliases, for example:
-
-```js
-/**
- * @typedef {import("./business/produktionApi.js").ProduktionApi} ProduktionApi
- */
-
-/**
- * @typedef {import("./fluentApi.js").FluentApi & {
- *   produktion: ProduktionApi;
- * }} IDASFluentApi
- */
-```
-
-This avoids ad hoc per-member typing strategies.
-
-
-### 4. DTO script files were converted into actual ES modules
-
-Some DTO files only contained `@typedef` declarations and no export. In practice, that can make `import("./file.js").Type` unstable or unusable.
-
-These DTO files were converted into modules by adding:
+If a file only contains typedefs, end it with:
 
 ```js
 export {};
 ```
 
-This was required in plain typedef-only files such as:
-
-- `api/dtos/belege.js`
-- `api/dtos/kunden.js`
-- `api/dtos/produktion.js`
-
-
-### 5. DTO cross-file dependencies were fixed
-
-Some DTOs referenced other DTOs from different files without importing them locally.
-
-Example of the broken pattern:
-
-```js
-/**
- * @typedef {Object} BelegDTO
- * @property {BeleganschriftDTO} BelegAdresse
- */
-```
-
-if `BeleganschriftDTO` lives in another file and is not imported locally.
+Without this, `import("./file.js").TypeName` can degrade to `any`.
 
-That was fixed by either:
 
-- adding a local typedef alias, or
-- using an inline import in the property type.
+### 2. Always include `.js` in import paths
 
-Example:
+Use:
 
 ```js
-/** @typedef {import('./kunden.js').BeleganschriftDTO} BeleganschriftDTO */
+import("../dtos/belege.js").VorgangDTO
 ```
 
-or:
+Not:
 
 ```js
- * @property {import('./kunden.js').BeleganschriftDTO} BelegAdresse
+import("../dtos/belege").VorgangDTO
 ```
 
 
-### 6. Missing DTO definitions in JSDoc were added
-
-Several DTO names used by the API surface existed in C# or were referenced in JS but were not actually modeled in JSDoc. Missing DTO definitions were added where source information was available.
-
-Examples added from source models:
+### 3. Import cross-file property types where they are used
 
-- `RechnungsNummer`
-- `ZusatztextDTO`
-- `BelegPositionSonderwunschDTO`
+If a DTO property refers to a type from another file, add a local alias or use an inline import.
 
-
-### 7. Business API method signatures were normalized
-
-Inline method-level types like this were reduced:
-
-```js
- * @returns {Promise<import('../dtos/index.js').ProduktionsfreigabeItemDTO[]>}
-```
-
-and replaced with local aliases at file top plus clean signatures:
+Preferred:
 
 ```js
-/** @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO */
+/** @typedef {import('./kunden.js').KontaktDTO} KontaktDTO */
 
 /**
- * @returns {Promise<ProduktionsfreigabeItemDTO[]>}
+ * @typedef {Object} VorgangDTO
+ * @property {KontaktDTO} Kunde
  */
-```
-
-This is easier to read, easier to maintain, and resolves more reliably in IntelliSense.
-
-
-### 8. `FluentApi` typedef usage was standardized
-
-Business API files must use:
 
-```js
-/** @typedef {import('../fluentApi.js').FluentApi} FluentApi */
-```
-
-and not:
-
-- a hand-written fake `FluentApi` object type
-- a missing typedef
-- an import path without `.js`
-
-
-## Files Touched By This Work
-
-The exact set may evolve later, but the primary files changed during this stabilization were:
-
-### API files
-
-- `api/idasFluentApi.js`
-- `api/business/benutzerApi.js`
-- `api/business/artikelApi.js`
-- `api/business/belegApi.js`
-- `api/business/produktionApi.js`
-- `api/business/fakturaApi.js`
-- `api/business/settingsApi.js`
-- `api/business/uiApi.js`
-- `api/business/utilityApi.js`
-- `api/business/serienApi.js`
-- `api/business/kontaktApi.js`
-- `api/business/belegPositionenApi.js`
-- `api/business/materialApi.js`
-
-### DTO files
-
-- `api/dtos/index.js`
-- `api/dtos/belege.js`
-- `api/dtos/kunden.js`
-- `api/dtos/produktion.js`
-- `api/dtos/settings.js`
-- `api/dtos/ui.js`
-- `api/dtos/technik.js`
-
-
-## The Rules
-
-These rules are mandatory if you want JSDoc discoverability to remain stable.
-
-
-## Rule 1: Every DTO file must be an ES module
-
-If a DTO file only contains typedefs, still add:
-
-```js
 export {};
 ```
 
-Why:
-
-- `import("./file.js").Type` is far more reliable when the target file is a real module.
-- Script files with only comments can cause type imports to degrade to `any`.
-
-Applies to:
-
-- DTO files
-- Any pure-type helper JS file used as a JSDoc import target
-
-
-## Rule 2: Use `.js` in all JSDoc import paths
-
-Always write:
+Also valid:
 
 ```js
-import("../dtos/belege.js").VorgangDTO
-```
-
-Never write:
-
-```js
-import("../dtos/belege").VorgangDTO
-```
-
-Why:
-
-- The repo is ESM.
-- The JS language service resolves explicit file extensions more consistently.
-
-
-## Rule 2a: Root DTO aliases must be generated, not hand-maintained
-
-The package root cannot rely on:
-
-```js
-export * from "./api/dtos/index.js"
-```
-
-to make JSDoc typedef aliases available through:
-
-```js
-import("@gandalan/weblibs").VorgangDTO
-```
-
-Why:
-
-- `export *` only forwards runtime exports.
-- JSDoc `@typedef` aliases are not runtime exports.
-- Root-level package imports therefore degrade to `any` unless the root module defines the aliases itself.
-
-The required pattern is:
-
-- keep `api/dtos/index.js` as the DTO alias source of truth
-- generate matching root typedef aliases into `index.js`
-- generate `index.d.ts` from the full package JSDoc source set for TypeScript consumers
-
-Do not edit the generated root DTO block manually. Regenerate it with:
-
-```bash
-npm run generate:root-dto-typedefs
-```
-
-The generator has two separate responsibilities:
-
-- `index.js`: generate the root DTO alias block for stable JSDoc imports from the package root
-- `index.d.ts`: generate root type exports for all non-trivial JSDoc-defined package types discovered in `index.js`, `api/**/*.js`, and `ui/**/*.js`
-
-For `index.d.ts`, simple local helper aliases like this are intentionally ignored:
-
-```js
-/** @typedef {import('../fluentApi.js').FluentApi} FluentApi */
-```
-
-because those are only local imports, not source type definitions. The declaration generator exports the canonical defining module instead.
-
-
-## Rule 3: DTO files must import cross-file DTO dependencies locally
-
-If a DTO property references a type from another DTO file, that dependency must be represented in the file itself.
-
-Preferred forms:
-
-```js
-/** @typedef {import('./kunden.js').BeleganschriftDTO} BeleganschriftDTO */
-```
-
-or directly in the property:
+/**
+ * @typedef {Object} VorgangDTO
+ * @property {import('./kunden.js').KontaktDTO} Kunde
+ */
 
-```js
- * @property {import('./kunden.js').BeleganschriftDTO} BelegAdresse
+export {};
 ```
 
-Never assume a type from another file is globally visible.
-
-Why:
-
-- Cross-file DTO references otherwise become weak links.
-- A top-level DTO may exist, but nested properties can still collapse to `any`.
 
+### 4. Keep API files readable with local aliases
 
-## Rule 4: API files should define local type aliases at the top
-
-At the top of each API file, create short local aliases for every DTO used in that file.
-
-Example:
+At the top of each API file, create short aliases for the types used in that file.
 
 ```js
 /**
  * @typedef {import('../fluentApi.js').FluentApi} FluentApi
  * @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO
- * @typedef {import('../dtos/produktion.js').ProduktionsInfoDTO} ProduktionsInfoDTO
  */
 ```
 
-Then use those aliases in method docs.
+Then use those aliases in `@param` and `@returns`.
 
-Why:
 
-- Method signatures stay readable.
-- Repeated inline import expressions are error-prone.
-- VS Code resolves these aliases more reliably than repeated deep inline imports.
+## Common Tasks
 
+### Add a property to an existing DTO
 
-## Rule 5: Prefer direct DTO source imports over aggregate imports when practical
+1. Open the concrete DTO owner file.
+2. Add the property with the exact runtime type.
+3. Import any cross-file type locally.
+4. Ensure the file ends with `export {};` if it is type-only.
 
-Preferred:
+Example:
 
 ```js
-/** @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO */
-```
+/** @typedef {import('./kunden.js').BeleganschriftDTO} BeleganschriftDTO */
 
-Acceptable when the type truly belongs to the index layer:
+/**
+ * @typedef {Object} BelegDTO
+ * @property {string} BelegGuid
+ * @property {BeleganschriftDTO} BelegAdresse
+ * @property {number | null} Total
+ */
 
-```js
-/** @typedef {import('../dtos/index.js').LoginDTO} LoginDTO */
+export {};
 ```
 
-Avoid defaulting everything to `dtos/index.js` when the concrete DTO source file is known.
-
-Why:
+Rules:
 
-- Fewer resolution layers.
-- Easier debugging.
-- Better discoverability of the true type owner.
+- Mark nullability explicitly.
+- Match runtime names exactly.
+- Mark optional properties only if they are actually optional.
 
 
-## Rule 6: Do not use circular factory typedef patterns
+### Add a function to a business API
 
-Do not do this:
+Use this pattern:
 
 ```js
 /**
- * @returns {ProduktionApi}
+ * @typedef {import('../fluentApi.js').FluentApi} FluentApi
+ * @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO
  */
-export function createProduktionApi(...) {}
 
-/**
- * @typedef {ReturnType<typeof createProduktionApi>} ProduktionApi
- */
-```
-
-If the exported API type is defined through `ReturnType<typeof createXApi>`, then the factory should not also declare `@returns {XApi}`.
-
-Correct pattern:
-
-```js
 /**
  * @param {FluentApi} fluentApi
  */
 export function createProduktionApi(fluentApi) {
     return {
-        ...
+        /**
+         * @returns {Promise<ProduktionsfreigabeItemDTO[]>}
+         */
+        getAllProduktionsfreigabeItems: () => fluentApi.get("ProduktionsfreigabeListe")
     };
 }
 
@@ -393,315 +162,188 @@ export function createProduktionApi(fluentApi) {
  */
 ```
 
+Important:
 
-## Rule 7: `idasFluentApi` members must use imported API aliases consistently
+- Do not also write `@returns {ProduktionApi}` on `createProduktionApi`.
+- The generator expands `ReturnType<typeof createXApi>` into the root `index.d.ts`.
 
-Correct pattern:
-
-```js
-/** @typedef {import('./business/produktionApi.js').ProduktionApi} ProduktionApi */
-
-/**
- * @typedef {import('./fluentApi.js').FluentApi & {
- *   produktion: ProduktionApi;
- * }} IDASFluentApi
- */
-```
-
-Do not mix:
-
-- imported alias types for some members
-- inline `ReturnType<typeof import(...).createXApi>` for others
-- unresolved local names for others
-
-One consistent member strategy must be used.
-
-
-## Rule 8: Every API file must define `FluentApi` the same way
-
-Always:
-
-```js
-/** @typedef {import('../fluentApi.js').FluentApi} FluentApi */
-```
-
-Never:
-
-- hand-write a fake subset object
-- omit it and still write `@param {FluentApi}`
-- use extensionless import paths
 
+### Add an optional API parameter
 
-## Rule 9: Optional parameters must be documented exactly
-
-If a parameter has a default value or is optional at call sites, mark it optional in JSDoc.
-
-Correct forms:
+Document it exactly as the runtime behaves.
 
 ```js
+/**
  * @param {boolean} [includeDetails=true]
- * @param {Date} [changedSince]
- * @param {string} [statusText='']
-```
-
-Rules:
-
-- Use square brackets for optional parameters.
-- Include the default if the runtime defines one.
-- The JSDoc type must match the runtime type exactly.
-- If `null` is accepted, include it explicitly.
-
-Examples:
-
-```js
  * @param {Date | null} [changedSince=null]
- * @param {boolean} [includeUIDefs=true]
- * @param {string[]} belegGuids
+ * @returns {Promise<AblageDTO[]>}
+ */
 ```
 
-Do not omit optionality when the implementation has a default value.
-
-
-## Rule 10: Method names, parameter names, and types must match runtime code exactly
-
-JSDoc is not a sketch. It must match the code.
-
-That means:
-
-- parameter order must match the function signature
-- parameter names must match the implementation
-- optional/default markers must match runtime defaults
-- return types must match actual API responses, not assumptions
+Use square brackets for optional parameters. Include default values when they exist.
 
-If the runtime returns a decoded JWT claims object, do not document it as a Swagger login DTO.
 
+### Add a root function export for consumers
 
-## Rule 11: DTO property types must be concrete where possible
-
-Prefer:
+If a function should be imported from the package root:
 
 ```js
- * @property {string} VorgangGuid
- * @property {number | null} VE_Menge
- * @property {Array<BelegPositionDTO>} PositionsObjekte
+import { fluentApi } from "@gandalan/weblibs";
 ```
 
-Avoid broad placeholders unless the source model is genuinely unknown.
-
-Use placeholders only when:
+then both of these must be true:
 
-- no source model exists in the repo
-- the backend contract is genuinely unknown
-- the placeholder is temporary and explicitly marked as such
+1. The function is exported from `index.js`.
+2. The root declaration output includes a stable signature in `index.d.ts`.
 
+In practice:
 
-## Rule 12: Placeholders are allowed, but they must be obvious and deliberate
+- add or keep the runtime export in `index.js`
+- update the generator if the root declaration needs an explicit function signature
+- run `npm run generate:dts`
 
-If a DTO cannot yet be modeled concretely, keep the placeholder explicit:
+Example consumer-facing signature:
 
-```js
-/** @typedef {Object} WebJobHistorieDTO */
+```ts
+export function fluentApi(url: string, authManager: FluentAuthManager | null, serviceName: string): FluentApi;
 ```
 
-and keep it centralized in `api/dtos/index.js` with a note that it is a placeholder.
-
-Do not scatter placeholder definitions across business API files.
-
-
-## Rule 13: Avoid duplicate semantic owners when possible
-
-There are two patterns in this repo:
-
-- concrete DTO file owns the actual shape
-- `dtos/index.js` re-exports or aliases it for convenience
+Rule of thumb:
 
-The concrete source file should remain the semantic owner of the shape.
+- runtime export alone is not enough
+- consumers need the root declaration too
 
-Examples:
 
-- `belege.js` owns `VorgangDTO`
-- `produktion.js` owns `ProduktionsfreigabeItemDTO`
-- `kunden.js` owns `KontaktDTO`
+### Add a public class for consumption
 
-`dtos/index.js` may alias them, but should not silently replace a concrete definition with a weaker one.
-
-
-## Rule 14: If a DTO file references types from C# sources, keep the JSDoc aligned to the source names
-
-If you add or fix a DTO from C#:
-
-- preserve the original name
-- preserve nullability where clear
-- preserve enum value meaning where clear
-- preserve nested object types when known
-
-Example fixes performed in this work came from C# source classes and enums.
-
-
-## Rule 15: Use clean method-level JSDoc, not deep import expressions
-
-Preferred:
+If you add a class that consumers should import directly:
 
 ```js
-/** @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO */
-
-/**
- * @returns {Promise<ProduktionsfreigabeItemDTO[]>}
- */
-getAllProduktionsfreigabeItems: () => fluentApi.get("ProduktionsfreigabeListe"),
+import { MyClient } from "@gandalan/weblibs";
 ```
 
-Avoid:
+follow this pattern:
 
 ```js
 /**
- * @returns {Promise<import('../dtos/index.js').ProduktionsfreigabeItemDTO[]>}
+ * Client for example operations.
  */
+export class MyClient {
+    /**
+     * @param {string} baseUrl
+     */
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+
+    /**
+     * @param {string} id
+     * @returns {Promise<string>}
+     */
+    async load(id) {
+        return `${this.baseUrl}/${id}`;
+    }
+}
 ```
 
+To make it consumable:
 
-## Rule 16: Keep JSDoc formatting strict
-
-Formatting affects readability and can affect tooling robustness.
-
-Rules:
+1. Export the class from its source file.
+2. Re-export it from `index.js` if it belongs at the package root.
+3. Run `npm run generate:dts`.
+4. Verify the class shape appears in `index.d.ts`.
 
-- keep indentation consistent with the file
-- keep comment stars aligned
-- do not leave malformed comment lines
-- do not mix single-quote and double-quote styles against repo lint rules
-- run lint fix after large edits in `WebLibs`
+For helper-only local classes that are not part of the public API, do not expose them at the root.
 
 
-## Recommended Patterns
+### Add a new standalone public type
 
-### Pattern A: DTO-only module
+If you add a new manual type file such as `api/someTypes.js`, keep it simple:
 
 ```js
 /**
- * @typedef {Object} ExampleDTO
- * @property {string} Guid
- * @property {number | null} Version
+ * @typedef {Object} ExampleOptions
+ * @property {string} id
+ * @property {boolean} [enabled=true]
  */
 
 export {};
 ```
 
+If that type must be visible to consumers, make sure the file is part of the generator input and regenerate declarations.
 
-### Pattern B: DTO with cross-file dependency
 
-```js
-/** @typedef {import('./kunden.js').KontaktDTO} KontaktDTO */
+## Root Consumption Model
 
-/**
- * @typedef {Object} VorgangDTO
- * @property {KontaktDTO} Kunde
- */
+There are two public surfaces:
 
-export {};
-```
+- `index.js` for runtime exports and root JSDoc aliases
+- `index.d.ts` for consumer TypeScript declarations
 
+`npm run generate:dts` updates both.
 
-### Pattern C: Business API file
+Do not hand-edit generated root blocks unless you are changing the generator itself.
 
-```js
-/**
- * @typedef {import('../fluentApi.js').FluentApi} FluentApi
- * @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO
- */
 
-/**
- * @param {FluentApi} fluentApi
- */
-export function createProduktionApi(fluentApi) {
-    return {
-        /**
-         * @returns {Promise<ProduktionsfreigabeItemDTO[]>}
-         */
-        getAllProduktionsfreigabeItems: () => fluentApi.get("ProduktionsfreigabeListe")
-    };
-}
+## What to Prefer
 
-/**
- * @typedef {ReturnType<typeof createProduktionApi>} ProduktionApi
- */
-```
+Prefer:
 
+```js
+/** @typedef {import('../dtos/produktion.js').ProduktionsfreigabeItemDTO} ProduktionsfreigabeItemDTO */
+```
 
-### Pattern D: Optional parameter with default
+Over:
 
 ```js
 /**
- * @param {boolean} [includeDetails=true]
- * @param {Date | null} [changedSince=null]
- * @returns {Promise<AblageDTO[]>}
+ * @returns {Promise<import('../dtos/index.js').ProduktionsfreigabeItemDTO[]>}
  */
 ```
 
+Prefer concrete DTO owner files over `dtos/index.js` when the owning file is known.
 
-## Edge Cases Checklist
-
-Before finishing any JSDoc work, verify all of the following.
-
-### DTO checklist
 
-- The DTO file is an ES module.
-- Every cross-file DTO property type is imported locally or written as an inline import.
-- Every enum-like type is documented with the correct primitive union or numeric union.
-- Nullability is explicit.
-- Arrays use `Type[]` or `Array<Type>` consistently.
-- No referenced type name exists only in C# while missing from JSDoc.
-- If a placeholder remains, it is explicit and centralized.
+## What to Avoid
 
-### API checklist
+Avoid these patterns:
 
-- `FluentApi` is imported with `.js`.
-- DTOs used in method docs have top-of-file aliases.
-- No inline `import('../dtos/index.js').Type` remains in `@param` or `@returns` unless there is a deliberate reason.
-- Optional parameters use square-bracket syntax.
-- Default values in code are reflected in JSDoc.
-- There is no circular `@returns {XApi}` with `ReturnType<typeof createXApi>`.
-- The exported `XApi` typedef exists at the end of the file.
-
-### `idasFluentApi` checklist
-
-- Every business member type is imported explicitly.
-- All member properties use one consistent typing strategy.
-- The `userInfo` type matches the runtime object shape, not a guessed backend DTO.
+- extensionless JSDoc imports
+- DTO files without `export {}`
+- cross-file DTO references with no local import
+- repeating deep inline imports in every method signature
+- circular API return typing
+- exposing a runtime export without making sure it is declared at the root
 
 
 ## Validation Workflow
 
-Whenever you touch JSDoc in `WebLibs`, validate in this order.
+When you change public JSDoc or exports:
 
-1. Fix local file diagnostics.
-2. Ensure DTO files are ES modules.
-3. Ensure DTO cross-file property references are imported locally.
-4. Ensure API files use local DTO aliases.
-5. Ensure no circular API `ReturnType` patterns remain.
-6. Run ESLint fix on changed files.
-7. Restart the TS server if IntelliSense still shows stale `any`.
+1. Fix diagnostics in the file you changed.
+2. Run `npm run generate:dts`.
+3. Check that `index.js` and `index.d.ts` reflect the new public shape.
+4. Verify IntelliSense from the package root.
 
 
-## Known Remaining Risk
+## Quick Checklist
 
-`api/dtos/index.js` still contains some placeholder DTOs that were kept intentionally because no complete JSDoc source model was fully introduced in this pass.
+Before you finish, confirm:
 
-That is acceptable for now as long as:
-
-- they remain explicit placeholders
-- they do not replace stronger concrete definitions
-- they are upgraded when the source DTO shape becomes available
+- the file uses `.js` JSDoc imports
+- type-only files end with `export {}`
+- DTO property types are imported locally when needed
+- public API methods use local aliases
+- new root exports are present in both runtime and declarations
+- `npm run generate:dts` has been run
 
 
 ## Bottom Line
 
-If you follow these rules, JSDoc discoverability in this repo stays stable.
-
-The three most important requirements are:
+If you want a property, function, or class to be easy for consumers to use, do three things:
 
-1. DTO files must be ES modules.
-2. DTO cross-file property types must be imported locally.
-3. API files must use local typedef aliases and avoid circular or overly indirect typing.
+1. Define the type clearly in the owning file.
+2. Export it through the correct public surface.
+3. Regenerate the root declarations.
 
-If one of those three is violated, IntelliSense will often fall back to `any` even though the comments look valid at first glance.
+That is the whole system.