u

docs/api/routes-all.md

@@ -57,6 +57,9 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body).
 
 ### Routes
 
+
+### Section: /account
+
 #### List accounts — `GET /account`
 _none_
 - Returns: `200 { accounts: { id: int, companyId: int, type: str, name: str }[] }`
@@ -66,6 +69,9 @@ _none_
 #### Delete account — `DELETE /account/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /article
+
 #### Create article in category — `POST /article`
 - Params: `body: { categoryId: int, name: str, desc?: str, seo?: str, track_stock?: bool }`
 - Returns: `201 T30`
@@ -171,6 +177,9 @@ _none_
 #### Set article weight by SKU — `PUT /article/{sku}/weight`
 - Params: `sku: str, body: { weight: num }`
 - Returns: `200 T1`
+
+### Section: /attributename
+
 #### List attribute names — `GET /attributename`
 _none_
 - Returns: `200 { attributenames: T24[] }`
@@ -195,12 +204,18 @@ _none_
 #### Update attribute name — `PATCH /attributename/{id}`
 - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }`
 - Returns: `200 { attributename: T24 }`
+
+### Section: /attributevalue
+
 #### Delete attribute value — `DELETE /attributevalue/{id}`
 - Params: `id: int`
 - Returns: `200 { ok: bool }`
 #### Update attribute value — `PATCH /attributevalue/{id}`
 - Params: `id: int, body: { value?: str, sort?: int }`
 - Returns: `200 { attributevalue: T38 }`
+
+### Section: /auth
+
 #### Login with Google ID token — `POST /auth/login`
 - Params: `body: { idToken: str }`
 - Returns: `200 { message: str, user: T34 }`
@@ -213,6 +228,9 @@ _none_
 #### Set selected company — `PUT /auth/selected-company`
 - Params: `body: { companyId: int }`
 - Returns: `200 { user: T34 }`
+
+### Section: /brand
+
 #### List brands — `GET /brand`
 - Params: `query: offset?: int, limit?: int, includeSmallThumbs?: bool`
 - Returns: `200 { brands: { id: int, name: str, pics: { fullHash: str, thumbW: int, thumbH: int, thumbHash: str, smallThumbW?: int|null, smallThumbH?: int|null, smallThumbBinary?: str|null }[], gsprpinfo?: str|null }[], total: int, offset: int, limit: int }`
@@ -231,6 +249,9 @@ _none_
 #### Add or replace brand image — `POST /brand/{id}/image`
 - Params: `id: int, image/avif`
 - Returns: `201 { brand: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T36[] } }`
+
+### Section: /category
+
 #### Create category — `POST /category`
 - Params: `body: { parentId: int, name: str }`
 - Returns: `201 { category: { id: int, parentId: int|null, sort: int, name: str } }`
@@ -273,6 +294,9 @@ _none_
 #### Delete category property — `DELETE /category/{id}/property/{propertyId}`
 - Params: `id: int, propertyId: int`
 - Returns: `200 { ok: bool }`
+
+### Section: /company
+
 #### List companies — `GET /company`
 _none_
 - Returns: `200 { companies: T32[] }`
@@ -303,6 +327,9 @@ _none_
 #### Update company — `PUT /company/{id}`
 - Params: `id: int, body: { iso639: str, name: str, taxrate: num, reducedtaxrate: num }`
 - Returns: `200 { company: T32 }`
+
+### Section: /customergroup
+
 #### List customer groups — `GET /customergroup`
 _none_
 - Returns: `200 { customergroups: { id: int, name: str, sort: int, editable: bool }[] }`
@@ -318,6 +345,9 @@ _none_
 #### Update customer group — `PATCH /customergroup/{id}`
 - Params: `id: int, body: { name: str }`
 - Returns: `200 { customergroup: T44 }`
+
+### Section: /delivery
+
 #### List deliveries — `GET /delivery`
 _none_
 - Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T40 }[] }`
@@ -348,6 +378,9 @@ _none_
 #### Get delivery attachment file content — `GET /delivery/{id}/file/{fileId}`
 - Params: `id: int, fileId: int, query: download?: bool`
 - Returns: `200 str`
+
+### Section: /entity
+
 #### List entities — `GET /entity`
 - Params: `query: customergroupId?: int, role?: str`
 - Returns: `200 { entities: T27[] }`
@@ -390,6 +423,9 @@ _none_
 #### Update entity — `PATCH /entity/{id}`
 - Params: `id: int, body: { name?: str, firstName?: str|null, number?: str|null }`
 - Returns: `200 T19`
+
+### Section: /events
+
 #### Subscribe to update signals (SSE) — `GET /events`
 _none_
 - Returns: `200 SSE`
@@ -409,12 +445,21 @@ _none_
   - `modelconversation`: `{}`
   - `modelconversation-<id>`: `{}`
   - `brand`: `{ sender, brandId }`
+
+### Section: /health
+
 #### Database health check — `GET /health`
 _none_
 - Returns: `200 { ok: bool }`
+
+### Section: /image
+
 #### Full image by hash — `GET /image/{fullHash}`
 - Params: `fullHash: str`
 - Returns: `200 avif`
+
+### Section: /labeltemplate
+
 #### List label templates — `GET /labeltemplate`
 _none_
 - Returns: `200 { labeltemplates: { id: int, name: str, width: num, height: num, dpi: int, type: str, thumb?: str|null }[] }`
@@ -433,6 +478,9 @@ _none_
 #### Update label template — `PUT /labeltemplate/{id}`
 - Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T17 }`
 - Returns: `200 T5`
+
+### Section: /ledger
+
 #### Query ledger by manifest article ID or SKU — `GET /ledger`
 - Params: `query: manifestarticle_id?: int, sku?: str, transaction_type?: str`
 - Returns: `200 T14`
@@ -445,6 +493,9 @@ _none_
 #### Query ledger by article SKU — `GET /ledger/sku/{sku}`
 - Params: `sku: str, query: transaction_type?: str`
 - Returns: `200 T14`
+
+### Section: /modelconversation
+
 #### List conversations — `GET /modelconversation`
 _none_
 - Returns: `200 { conversations: T29[] }`
@@ -466,12 +517,18 @@ _none_
 #### Stream conversation events (SSE) — `GET /modelconversation/{id}/stream`
 - Params: `id: int`
 - Returns: `200 SSE`
+
+### Section: /number
+
 #### List number sequences — `GET /number`
 _none_
 - Returns: `200 { numbers: { id: int, type: str, prefix: str, padding: int, next: int }[] }`
 #### Update number sequence — `PATCH /number/{id}`
 - Params: `id: int, body: { prefix?: str, padding?: int, next?: int }`
 - Returns: `200 { number: { id: int, type: str, prefix: str, padding: int, next: int } }`
+
+### Section: /order
+
 #### List orders — `GET /order`
 - Params: `query: offset?: int, limit?: int`
 - Returns: `200 { orders: T11[], total: int, offset: int, limit: int }`
@@ -499,12 +556,21 @@ _none_
 #### Create shipping for an order — `POST /order/{id}/shipping`
 - Params: `id: int, body: { type: str, state: str }`
 - Returns: `201 { shipping: { id: int, manifestId: int, number: str, type: str, state: str } }`
+
+### Section: /package
+
 #### Delete package — `DELETE /package/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /payment
+
 #### Delete payment — `DELETE /payment/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /posterminal
+
 #### List POS terminals — `GET /posterminal`
 _none_
 - Returns: `200 { posterminals: T10[] }`
@@ -529,6 +595,9 @@ _none_
 #### Enable category on terminal — `PUT /posterminal/{id}/category/{categoryId}`
 - Params: `id: int, categoryId: int`
 - Returns: `200 T45`
+
+### Section: /printer
+
 #### List printers — `GET /printer`
 _none_
 - Returns: `200 { printers: T23[] }`
@@ -550,6 +619,9 @@ _none_
 #### Update printer — `PUT /printer/{id}`
 - Params: `id: int, body: { address?: str, type?: str, model?: str|null, serial?: str|null, sort?: int, desc?: str|null }`
 - Returns: `200 T18`
+
+### Section: /propertyname
+
 #### List property names — `GET /propertyname`
 _none_
 - Returns: `200 { propertynames: T41[] }`
@@ -565,6 +637,9 @@ _none_
 #### Update property name — `PATCH /propertyname/{id}`
 - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }`
 - Returns: `200 { propertyname: T41 }`
+
+### Section: /public
+
 #### Receipt crash dump — `POST /public/telemetry/crash`
 - Params: `body: { content: any }`
 - Returns: `200 { ok: bool, filename: str }`
@@ -577,6 +652,9 @@ _none_
 #### List public categories — `GET /public/{companyId}/categories`
 - Params: `companyId: int`
 - Returns: `200 { categories: { id: int, parentId: int|null, sort: int, name: str, slug: str, fullHash: str|null, thumbW: int|null, thumbH: int|null, thumbHash: str|null }[] }`
+
+### Section: /quote
+
 #### List quotes — `GET /quote`
 _none_
 - Returns: `200 { quotes: { id: int, number: str, type: str, entityId: int|null, date: str, createdAt?: str }[] }`
@@ -592,6 +670,9 @@ _none_
 #### Update quote — `PATCH /quote/{id}`
 - Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T25[] }`
 - Returns: `200 T8`
+
+### Section: /serper
+
 #### Crawl image from URL, crop white/transparency borders, and return AVIF — `POST /serper/image`
 - Params: `body: { url: str }`
 - Returns: `200 avif`
@@ -604,6 +685,9 @@ _none_
   - `thumb`: `{ "id": 0, "dataUrl": "data:image/webp;base64,…" }`
   - `done`: `{ "total": 100 }`
   - `error`: `{ "error": "…" }`
+
+### Section: /shipping
+
 #### Delete shipping — `DELETE /shipping/{id}`
 - Params: `id: int`
 - Returns: `204 void`
@@ -613,12 +697,21 @@ _none_
 #### Create package for a shipping — `POST /shipping/{id}/package`
 - Params: `id: int, body: { entityaddressId: int, type: str, state: str, details?: str }`
 - Returns: `201 { package: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null } }`
+
+### Section: /smallthumb
+
 #### Small thumb image by hash — `GET /smallthumb/{fullHash}`
 - Params: `fullHash: str`
 - Returns: `200 avif`
+
+### Section: /stock
+
 #### Adjust stock manually — `POST /stock/adjust`
 - Params: `body: { sku?: str, warehouseId?: int, amount?: num, text?: str|null, lines?: { sku: str, amount: num, warehouseId?: int, text?: str }[] }`
 - Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T15[] }`
+
+### Section: /supplier
+
 #### List suppliers — `GET /supplier`
 _none_
 - Returns: `200 { suppliers: T39[] }`
@@ -637,9 +730,15 @@ _none_
 #### Query supplier articles by SKUs (bulk) — `POST /supplier/{id}/articles`
 - Params: `id: int, body?: { skus?: str[] }`
 - Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T43|null }[] }`
+
+### Section: /thumb
+
 #### Thumb image by hash — `GET /thumb/{fullHash}`
 - Params: `fullHash: str`
 - Returns: `200 avif`
+
+### Section: /unit
+
 #### Delete unit — `DELETE /unit`
 - Params: `query: si: str`
 - Returns: `204 void`
@@ -649,6 +748,9 @@ _none_
 #### Upsert unit — `PUT /unit`
 - Params: `body: { si: str, basesi: str, basesifactor: num, symbol: str, name: str }`
 - Returns: `200 { unit: T31 }`
+
+### Section: /v1
+
 #### JTL-POS category synchronization — `GET /v1/category`
 - Params: `query: lastChangedCategory?: str, limit?: int`
 - Returns: `200 {}[]`
@@ -664,6 +766,9 @@ _none_
 #### JTL-POS product catalog synchronization — `GET /v1/product`
 - Params: `query: lastChangedProduct?: str, limit?: int`
 - Returns: `200 {}[]`
+
+### Section: /vfs
+
 #### List virtual filesystem files — `GET /vfs`
 _none_
 - Returns: `200 { files: { name: str, size: int, mime: str, updated_at: str, created_at: str, isText: bool, isImage: bool, isPdf: bool }[] }`
@@ -688,6 +793,9 @@ _none_
 #### Create or overwrite a virtual filesystem file — `PUT /vfs/{*path}`
 - Params: `path: str, body: { content: str, mime?: str }`
 - Returns: `200 { success: bool, file: { name: str, size: int, mime: str, updated_at: str } }`
+
+### Section: /warehouse
+
 #### List warehouses — `GET /warehouse`
 _none_
 - Returns: `200 { warehouses: T44[] }`

docs/api/routes.md

@@ -52,6 +52,9 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body).
 
 ### Routes
 
+
+### Section: /account
+
 #### List accounts — `GET /account`
 _none_
 - Returns: `200 { accounts: { id: int, companyId: int, type: str, name: str }[] }`
@@ -61,6 +64,9 @@ _none_
 #### Delete account — `DELETE /account/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /article
+
 #### Create article in category — `POST /article`
 - Params: `body: { categoryId: int, name: str, desc?: str, seo?: str, track_stock?: bool }`
 - Returns: `201 T28`
@@ -160,6 +166,9 @@ _none_
 #### Set article weight by SKU — `PUT /article/{sku}/weight`
 - Params: `sku: str, body: { weight: num }`
 - Returns: `200 T1`
+
+### Section: /attributename
+
 #### List attribute names — `GET /attributename`
 _none_
 - Returns: `200 { attributenames: T23[] }`
@@ -184,18 +193,27 @@ _none_
 #### Update attribute name — `PATCH /attributename/{id}`
 - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }`
 - Returns: `200 { attributename: T23 }`
+
+### Section: /attributevalue
+
 #### Delete attribute value — `DELETE /attributevalue/{id}`
 - Params: `id: int`
 - Returns: `200 { ok: bool }`
 #### Update attribute value — `PATCH /attributevalue/{id}`
 - Params: `id: int, body: { value?: str, sort?: int }`
 - Returns: `200 { attributevalue: T34 }`
+
+### Section: /auth
+
 #### Login with Google ID token — `POST /auth/login`
 - Params: `body: { idToken: str }`
 - Returns: `200 { message: str, user: { id: int, email: str, selectedCompanyId: int|null, picture?: str } }`
 #### Logout — `POST /auth/logout`
 _none_
 - Returns: `200 { message: str }`
+
+### Section: /brand
+
 #### List brands — `GET /brand`
 - Params: `query: offset?: int, limit?: int, includeSmallThumbs?: bool`
 - Returns: `200 { brands: { id: int, name: str, pics: { fullHash: str, thumbW: int, thumbH: int, thumbHash: str, smallThumbW?: int|null, smallThumbH?: int|null, smallThumbBinary?: str|null }[], gsprpinfo?: str|null }[], total: int, offset: int, limit: int }`
@@ -214,6 +232,9 @@ _none_
 #### Add or replace brand image — `POST /brand/{id}/image`
 - Params: `id: int, image/avif`
 - Returns: `201 { brand: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: T32[] } }`
+
+### Section: /category
+
 #### Create category — `POST /category`
 - Params: `body: { parentId: int, name: str }`
 - Returns: `201 { category: { id: int, parentId: int|null, sort: int, name: str } }`
@@ -250,6 +271,9 @@ _none_
 #### Delete category property — `DELETE /category/{id}/property/{propertyId}`
 - Params: `id: int, propertyId: int`
 - Returns: `200 { ok: bool }`
+
+### Section: /company
+
 #### List companies — `GET /company`
 _none_
 - Returns: `200 { companies: { id: int, iso639: str, name: str, taxrate: num, reducedtaxrate: num }[] }`
@@ -274,6 +298,9 @@ _none_
 #### Update company — `PUT /company/{id}`
 - Params: `id: int, body: { iso639: str, name: str, taxrate: num, reducedtaxrate: num }`
 - Returns: `200 { company: { id: int, iso639: str, name: str, taxrate: num, reducedtaxrate: num } }`
+
+### Section: /customergroup
+
 #### List customer groups — `GET /customergroup`
 _none_
 - Returns: `200 { customergroups: { id: int, name: str, sort: int, editable: bool }[] }`
@@ -289,6 +316,9 @@ _none_
 #### Update customer group — `PATCH /customergroup/{id}`
 - Params: `id: int, body: { name: str }`
 - Returns: `200 { customergroup: T40 }`
+
+### Section: /delivery
+
 #### List deliveries — `GET /delivery`
 _none_
 - Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T36 }[] }`
@@ -307,6 +337,9 @@ _none_
 #### Get delivery attachment file content — `GET /delivery/{id}/file/{fileId}`
 - Params: `id: int, fileId: int, query: download?: bool`
 - Returns: `200 str`
+
+### Section: /entity
+
 #### List entities — `GET /entity`
 - Params: `query: customergroupId?: int, role?: str`
 - Returns: `200 { entities: T26[] }`
@@ -349,6 +382,9 @@ _none_
 #### Update entity — `PATCH /entity/{id}`
 - Params: `id: int, body: { name?: str, firstName?: str|null, number?: str|null }`
 - Returns: `200 T18`
+
+### Section: /labeltemplate
+
 #### List label templates — `GET /labeltemplate`
 _none_
 - Returns: `200 { labeltemplates: { id: int, name: str, width: num, height: num, dpi: int, type: str, thumb?: str|null }[] }`
@@ -367,6 +403,9 @@ _none_
 #### Update label template — `PUT /labeltemplate/{id}`
 - Params: `id: int, body: { name?: str, width?: num, height?: num, dpi?: int, type?: str, content?: T16 }`
 - Returns: `200 T5`
+
+### Section: /ledger
+
 #### Query ledger by manifest article ID or SKU — `GET /ledger`
 - Params: `query: manifestarticle_id?: int, sku?: str, transaction_type?: str`
 - Returns: `200 T13`
@@ -379,12 +418,18 @@ _none_
 #### Query ledger by article SKU — `GET /ledger/sku/{sku}`
 - Params: `sku: str, query: transaction_type?: str`
 - Returns: `200 T13`
+
+### Section: /number
+
 #### List number sequences — `GET /number`
 _none_
 - Returns: `200 { numbers: { id: int, type: str, prefix: str, padding: int, next: int }[] }`
 #### Update number sequence — `PATCH /number/{id}`
 - Params: `id: int, body: { prefix?: str, padding?: int, next?: int }`
 - Returns: `200 { number: { id: int, type: str, prefix: str, padding: int, next: int } }`
+
+### Section: /order
+
 #### List orders — `GET /order`
 - Params: `query: offset?: int, limit?: int`
 - Returns: `200 { orders: T10[], total: int, offset: int, limit: int }`
@@ -412,12 +457,21 @@ _none_
 #### Create shipping for an order — `POST /order/{id}/shipping`
 - Params: `id: int, body: { type: str, state: str }`
 - Returns: `201 { shipping: { id: int, manifestId: int, number: str, type: str, state: str } }`
+
+### Section: /package
+
 #### Delete package — `DELETE /package/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /payment
+
 #### Delete payment — `DELETE /payment/{id}`
 - Params: `id: int`
 - Returns: `204 void`
+
+### Section: /printer
+
 #### List printers — `GET /printer`
 _none_
 - Returns: `200 { printers: T22[] }`
@@ -439,6 +493,9 @@ _none_
 #### Update printer — `PUT /printer/{id}`
 - Params: `id: int, body: { address?: str, type?: str, model?: str|null, serial?: str|null, sort?: int, desc?: str|null }`
 - Returns: `200 T17`
+
+### Section: /propertyname
+
 #### List property names — `GET /propertyname`
 _none_
 - Returns: `200 { propertynames: T37[] }`
@@ -454,6 +511,9 @@ _none_
 #### Update property name — `PATCH /propertyname/{id}`
 - Params: `id: int, body: { name?: str, sort?: int, exclusive?: bool }`
 - Returns: `200 { propertyname: T37 }`
+
+### Section: /quote
+
 #### List quotes — `GET /quote`
 _none_
 - Returns: `200 { quotes: { id: int, number: str, type: str, entityId: int|null, date: str, createdAt?: str }[] }`
@@ -469,6 +529,9 @@ _none_
 #### Update quote — `PATCH /quote/{id}`
 - Params: `id: int, body: { number?: str, date?: str, entityId?: int|null, lines?: T24[] }`
 - Returns: `200 T8`
+
+### Section: /shipping
+
 #### Delete shipping — `DELETE /shipping/{id}`
 - Params: `id: int`
 - Returns: `204 void`
@@ -478,12 +541,21 @@ _none_
 #### Create package for a shipping — `POST /shipping/{id}/package`
 - Params: `id: int, body: { entityaddressId: int, type: str, state: str, details?: str }`
 - Returns: `201 { package: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null } }`
+
+### Section: /smallthumb
+
 #### Small thumb image by hash — `GET /smallthumb/{fullHash}`
 - Params: `fullHash: str`
 - Returns: `200 avif`
+
+### Section: /stock
+
 #### Adjust stock manually — `POST /stock/adjust`
 - Params: `body: { sku?: str, warehouseId?: int, amount?: num, text?: str|null, lines?: { sku: str, amount: num, warehouseId?: int, text?: str }[] }`
 - Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T14[] }`
+
+### Section: /supplier
+
 #### List suppliers — `GET /supplier`
 _none_
 - Returns: `200 { suppliers: T35[] }`
@@ -502,6 +574,9 @@ _none_
 #### Query supplier articles by SKUs (bulk) — `POST /supplier/{id}/articles`
 - Params: `id: int, body?: { skus?: str[] }`
 - Returns: `200 { articles: { id: int, articleId: int, entityId: int, pu: num, sort: int, article: { id: int, sku: str, name?: str|null, slug?: str|null, photos?: { sort: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str }[], eans?: str[] }, supplierName?: str|null, sku?: str|null, stock?: num|null, priceId?: int|null, price?: T39|null }[] }`
+
+### Section: /unit
+
 #### Delete unit — `DELETE /unit`
 - Params: `query: si: str`
 - Returns: `204 void`
@@ -511,6 +586,9 @@ _none_
 #### Upsert unit — `PUT /unit`
 - Params: `body: { si: str, basesi: str, basesifactor: num, symbol: str, name: str }`
 - Returns: `200 { unit: T29 }`
+
+### Section: /warehouse
+
 #### List warehouses — `GET /warehouse`
 _none_
 - Returns: `200 { warehouses: T40[] }`

scripts/generateApiDocs.js

@@ -770,7 +770,15 @@ function renderRoutesOverview(operations, title = 'Dash API Routes Overview') {
     lines.push('');
     lines.push('### Routes');
     lines.push('');
+    let currentSection = null;
     for (const op of operations) {
+        const section = op.path.split('/').filter(Boolean)[0] || '/';
+        if (section !== currentSection) {
+            currentSection = section;
+            lines.push('');
+            lines.push(`### Section: ${section === '/' ? '/' : `/${section}`}`);
+            lines.push('');
+        }
         const params = summarizeOperationParams(op.operation, aliases);
         const returns = summarizeOperationReturns(op.operation, aliases);
         const hasSseResponse = Object.values(op.operation.responses || {}).some((response) =>

src/services/conversationManager.js

@@ -33,7 +33,6 @@ import { resolveOpenRouterKey, resolveDefaultModel, resolveModelReasoning, RETIR
 
 const KEEP_ALIVE_MS = 20_000;
 
-const ROUTES_DOC_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '../../docs/api/routes.md');
 
 /**
  * Builds the SKILL index block for the system prompt.
@@ -103,103 +102,81 @@ async function buildSystemPrompt(vfsRoot, googleAuthId) {
         }
     }
 
-    let routesDoc = '';
-    try {
-        routesDoc = readFileSync(ROUTES_DOC_PATH, 'utf8').trim();
-    } catch (err) {
-        console.error('conversation: failed to read routes doc:', err);
-    }
     const today = new Date().toISOString().split('T')[0];
     const basePrompt = [
-        'Assistant for QuixPOS Article Management System REST API operation',
+        'QuixPOS Article Management System API Assistant',
         `Date: ${today}`,
         '',
-        'YOUR TOOLS:',
-        '1. dashback_request: HTTP requests (GET, POST, PUT, PATCH, DELETE) against QuixPOS Article Management System.',
-        '2. ask_user: Prompt user for clarification or decisions. Pauses execution until response.',
-        '3. javascript_execute: Sandboxed Node environment for computation, aggregation, and binary I/O. Assign module.exports. API: fetch("/path"). vfs, sharp, ExcelJS.',
-        '4. find_files: List VFS files. Set skills=true for SKILL files.',
-        '5. read_file: Read VFS text file (seek/limit windowed).',
-        '6. patch: Create, overwrite, or replace text in VFS files (only text write path; creates SKILL files).',
+        'TOOLS:',
+        '1. dashback_request: HTTP requests (GET, POST, PUT, PATCH, DELETE) to QuixPOS API.',
+        '2. ask_user: Prompt user for missing decisions or parameters; pauses until answered.',
+        '3. javascript_execute: Sandboxed Node env for computation, binary I/O, aggregation. Assign module.exports. Has fetch("/path"), vfs, sharp, ExcelJS.',
+        '4. find_files: List VFS files (skills=true for SKILL files).',
+        '5. read_file: Read VFS text/CSV/JSON files (seek/limit windowed).',
+        '6. patch: Create/overwrite/replace text in VFS files, incl. SKILL files (only text write path).',
         '7. search_images: Search Google Images; downloads AVIF candidates to VFS.',
-        '8. analyze_image: Inspect up to 9 images via vision model (VFS paths or "image/<hash>"). Always evaluate images through this tool.',
-        '9. web_search: Web search via Google. Filter with timePeriod ("day"/"week" for current events).',
-        '10. url_get: Fetch and scrape web page content/markdown.',
-        '11. pdf_read: Convert PDF/text to layout text ("txt") or VFS page images ("png").',
-        '12. reset_vfs: Delete VFS files/artifacts. Preserves SKILL files.',
-        '13. rm: Delete single VFS file (used to delete SKILL files or specific artifacts).',
-        '14. apisuggestionsorissues: Report missing API endpoints, bugs, or issues for triage.',
-        '15. search_articles: Search articles across name, brand, EAN, SKU, and supplier SKU. Returns window of full articles (default 3, max 20), offset, and total count.',
-        '16. edit_image: Generate or edit images using the configured company image model (modelslugimage). Supports attachments (low/high quality), size tiers (1K/2K/4K), and aspect ratios (1:1/4:3/3:4). Writes output to VFS (always AVIF format).',
-        '17. ean_checksum: Validate EAN/GTIN/UPC barcode check digits or calculate missing check digit for barcodes (EAN-13, EAN-8, UPC-A, GTIN-14).',
-        '18. net_gross_calc: Convert between net and gross prices with tax/VAT rate (default 19%). Provides 2-decimal display values and high-precision net prices for API article creation.',
-        '19. set-user-route: Navigate the user to a frontend route (e.g. when the user says "show me the article", "open quote 1001", or asks to view a page/entity).',
+        '8. analyze_image: Vision analysis of up to 9 images (VFS paths or "image/<hash>"). Always evaluate images with this tool.',
+        '9. web_search: Google web search (timePeriod: "day"|"week" for current events).',
+        '10. url_get: Fetch/scrape web page as markdown.',
+        '11. pdf_read: Convert PDF to layout text ("txt") or VFS page images ("png").',
+        '12. reset_vfs: Delete all non-SKILL VFS files.',
+        '13. rm: Delete a single VFS file (including SKILL files).',
+        '14. apisuggestionsorissues: Report API bugs or missing endpoints.',
+        '15. search_articles: Search by name, brand, EAN, SKU, supplier SKU. Returns full articles window (default 3, max 20), offset, total.',
+        '16. edit_image: Generate/edit images with the company image model (modelslugimage). Supports attachments (low/high quality), sizes 1K/2K/4K, ratios 1:1/4:3/3:4. Output: AVIF in VFS.',
+        '17. ean_checksum: Validate or generate barcode check digits (EAN-13, EAN-8, UPC-A, GTIN-14).',
+        '18. net_gross_calc: Convert gross/net with VAT (default 19%). Returns 2-decimal display values and high-precision net for the API.',
+        '19. set-user-route: Navigate the UI (e.g. "show me the article", "open quote 1001") using the Route Matrix.',
         '',
-        'VIRTUAL FILESYSTEM:',
-        '- Persistent per-company VFS. Paths are root-relative forward-slash (e.g. "labels/sheet1.png").',
-        '- Can host an entire static website (HTML, CSS, JS, images, etc.).',
-        '- Text: list with find_files, read with read_file, write with patch.',
-        '- User attachments are saved to VFS (e.g. "attachments/...") and tagged in user messages as `[ATTACHMENT name= path= type=]`. Inspect attachments with appropriate tools: `read_file` (text/csv/json), `pdf_read` (PDFs), `analyze_image` (images), or `javascript_execute` with `ExcelJS` (Excel spreadsheets).',
-        '- Markdown links: Internet links are "https://..." or simply "hostname.com" / "hostname.com/filename". A pure relative path with no dotted hostname is always a VFS relative path (e.g. `[download](report.csv)` or `![preview](images/photo.png)`).',
-        '',
-        'SKILL FILES:',
-        '- Reusable instruction docs: "<slug>.SKILL" at VFS root. First line is title, followed by markdown.',
-        '- Root-only (no "/"). Discover via find_files({ skills: true }).',
-        '- Read with read_file BEFORE starting covered tasks. Propose saving improved procedures as new SKILL files.',
-        '- Exempt from reset_vfs. Delete permanently via rm.',
+        'VFS & SKILLS:',
+        '- Persistent per-company VFS; root-relative forward-slash paths (e.g. "labels/sheet1.png"). Can host a static website.',
+        '- User uploads go to "attachments/…", tagged in messages as `[ATTACHMENT name= path= type=]`. Inspect with read_file (text/csv/json), pdf_read (PDF), analyze_image (images), javascript_execute + ExcelJS (spreadsheets).',
+        '- Markdown links: internet links are "https://…" or dotted hostnames ("hostname.com/file"); anything else is a VFS path (`[download](report.csv)`).',
+        '- SKILL files: root-only "<slug>.SKILL" markdown (first line = title). Discover via find_files({ skills: true }). ALWAYS read_file the matching skill BEFORE executing a covered task. Propose saving improved procedures as new SKILL files. Exempt from reset_vfs; delete via rm.',
         '',
         buildSkillIndex(vfsRoot),
         '',
-        'IMAGES:',
-        '- Evaluate images via analyze_image; report model findings.',
-        '- Flow: search_images("query") → analyze_image({ paths: [...], prompt: "…" }) → upload via fetch in javascript_execute.',
-        '- `image/` is READ-ONLY database storage. Write generated images elsewhere (e.g. "images/…").',
+        'RULES:',
+        '- PRICES: user input is GROSS, API requires NET. Always use net_gross_calc (4-6 decimals): net = gross / (1 + taxRate / 100).',
+        '- LABELS (/labeltemplate): Dashback JSON `{ "objects": [ ... ] }`. Do NOT use ZPL.',
+        '- IMAGES: flow search_images → analyze_image({ paths, prompt }) → upload via fetch in javascript_execute. `image/` is READ-ONLY; write generated images elsewhere (e.g. "images/…").',
+        '- OUTPUT: Markdown + emoji. Render VFS images inline `![alt](artifacts/example.png)`; other files (PDF, JSON, CSV) need download links.',
+        '- NAVIGATION: when the user asks to view/open a page or entity, call set-user-route with a path from the matrix.',
+        '- API: routes are not inlined. BEFORE dashback_request, read_file the api-<section>.SKILL for exact params and response shapes. `api-binary-streaming-routes.SKILL` covers fetch()-only routes.',
         '',
-        'OPERATING GUIDELINES:',
-        '- GROSS vs NET PRICES: User prices are almost always GROSS (incl. VAT); API requires NET. Use net_gross_calc to compute high-precision (4–6 decimals) NET prices for API requests: `net = gross / (1 + taxRate / 100)`.',
-        '- DISPLAYING GENERATED IMAGES: Inline markdown images supported. Embed written VFS image paths: `![descriptive alt](artifacts/example.png)`. Other files (PDF, JSON, CSV) do not render inline; provide download links.',
-        '- LABEL TEMPLATES (/labeltemplate): Must use Dashback JSON schema `{ "objects": [ ... ] }`. Do NOT use ZPL.',
-        '- USER NAVIGATION: When the user says "show me the article", "open this order", or asks to navigate to a screen/entity, call set-user-route with the appropriate path from the Route Construction Matrix.',
-        '- Always Format output with markdown and emoji.',
+        'BINARY IMAGE UPLOAD (fetch() in javascript_execute, image/avif buffer body):',
+        '- POST /article/{sku}/image -> 201 { image: { picId, sort, full: { w, h, size }, thumb: { w, h }, hash, thumbHash } }',
+        '- POST /category/{id}/image -> 201 { category: { id, thumbW, thumbH, thumbHash } }',
+        '- POST /brand/{id}/image -> 201 { brand: { id, fullHash, thumbW, thumbH, thumbHash, pics: [...] } }',
         '',
-        'USER PERSPECTIVE ROUTE CONSTRUCTION MATRIX:',
-        '| Destination | Path Pattern | Parameters / Construction | Example |',
+        'ROUTE MATRIX (client routes German, API sections English; skills = api-<section>):',
+        '| Destination | Path | Example | API sections |',
         '|:---|:---|:---|:---|',
-        '| **Article Search / Index** | `/artikel` | Query params: `?target={query}&filter={filter}&offset={n}` | `/artikel?target=kabel` |',
-        '| **Article Detail** | `/artikel/:sku` | Encode SKU: `/artikel/${encodeURIComponent(sku)}` | `/artikel/ART-10042` |',
-        '| **Warehouse / Stock** | `/artikel/lager` | Static | `/artikel/lager` |',
-        '| **Brands** | `/artikel/marken` | Static | `/artikel/marken` |',
-        '| **Label Templates** | `/artikel/vorlagen` | Static | `/artikel/vorlagen` |',
-        '| **Attributes & Features** | `/artikel/merkmale` | Static | `/artikel/merkmale` |',
-        '| **Category Tree Root** | `/kategorien` | Static | `/kategorien` |',
-        '| **Category Subtree** | `/kategorien/*` | Join encoded slugs: `/kategorien/${slug1}/${slug2}` | `/kategorien/elektronik/kabel` |',
-        '| **Delivery List** | `/lieferung` | Static | `/lieferung` |',
-        '| **New Delivery Draft** | `/lieferung/neu` | Static (receipt & draft line editor) | `/lieferung/neu` |',
-        '| **Delivery Detail** | `/lieferung/:deliveryId` | Delivery document ID: `/lieferung/${deliveryId}` | `/lieferung/42` |',
-        '| **Suppliers Directory** | `/lieferung/lieferanten` | Static | `/lieferung/lieferanten` |',
-        '| **Quote List (Angebote)** | `/auftrag` | Static | `/auftrag` |',
-        '| **New Quote** | `/auftrag/neu` | Static draft form | `/auftrag/neu` |',
-        '| **Quote Detail** | `/auftrag/:quoteId` | Quote document ID: `/auftrag/${quoteId}` | `/auftrag/1001` |',
-        '| **Order List (Bestellungen)**| `/auftrag/bestellung` | Static | `/auftrag/bestellung` |',
-        '| **New Order** | `/auftrag/bestellung/neu` | Static draft form | `/auftrag/bestellung/neu` |',
-        '| **Order Detail** | `/auftrag/bestellung/:orderId` | Order document ID: `/auftrag/bestellung/${orderId}` | `/auftrag/bestellung/2005` |',
-        '| **Customer List** | `/kunde` | Static | `/kunde` |',
-        '| **New Customer** | `/kunde/neu` | Static form | `/kunde/neu` |',
-        '| **Customer Detail** | `/kunde/:entityId` | Customer entity ID: `/kunde/${entityId}` | `/kunde/312` |',
-        '| **Customer Groups** | `/kunde/gruppen` | Static (pricing & customer tiers) | `/kunde/gruppen` |',
-        '| **Article History** | `/infos` or `/infos/articlehistory` | Static | `/infos/articlehistory` |',
-        '| **Global History** | `/infos/globalhistory` | Static audit log | `/infos/globalhistory` |',
-        '| **Statistics** | `/infos/statistics` | Static KPIs & charts | `/infos/statistics` |',
-        ...(routesDoc ? [
-            '',
-            'DASHBACK API ROUTES:',
-            'Binary image upload routes (use via fetch() in javascript_execute with image/avif buffer body):',
-            '- POST /article/{sku}/image (Params: sku: str, body: image/avif -> 201 { image: { picId: int, sort: int, full: { w, h, size }, thumb: { w, h }, hash: str, thumbHash: str } })',
-            '- POST /category/{id}/image (Params: id: int, body: image/avif -> 201 { category: { id: int, thumbW: int, thumbH: int, thumbHash: str } })',
-            '- POST /brand/{id}/image (Params: id: int, body: image/avif -> 201 { brand: { id: int, fullHash: str, thumbW: int, thumbH: int, thumbHash: str, pics: [...] } })',
-            '',
-            routesDoc,
-        ] : []),
+        '| Article Search | `/artikel?target={query}&filter={filter}&offset={n}` | `/artikel?target=kabel` | article, category, brand |',
+        '| Article Detail | `/artikel/${encodeURIComponent(sku)}` | `/artikel/ART-10042` | article, category, brand, attributename, propertyname, unit, supplier, printer, labeltemplate, ledger |',
+        '| Warehouse / Stock | `/artikel/lager` | `/artikel/lager` | warehouse, stock, ledger |',
+        '| Brands | `/artikel/marken` | `/artikel/marken` | brand |',
+        '| Label Templates | `/artikel/vorlagen` | `/artikel/vorlagen` | labeltemplate, printer |',
+        '| Attributes | `/artikel/merkmale` | `/artikel/merkmale` | attributename, attributevalue, propertyname |',
+        '| Category Root | `/kategorien` | `/kategorien` | category |',
+        '| Category Subtree | `/kategorien/${slug1}/${slug2}` (encoded slugs) | `/kategorien/elektronik/kabel` | category, article |',
+        '| Delivery List | `/lieferung` | `/lieferung` | delivery |',
+        '| New Delivery | `/lieferung/neu` | `/lieferung/neu` | delivery, supplier, article, warehouse, stock |',
+        '| Delivery Detail | `/lieferung/${deliveryId}` | `/lieferung/42` | delivery, supplier, ledger |',
+        '| Suppliers | `/lieferung/lieferanten` | `/lieferung/lieferanten` | supplier |',
+        '| Quote List | `/auftrag` | `/auftrag` | quote |',
+        '| New Quote | `/auftrag/neu` | `/auftrag/neu` | quote, entity, article |',
+        '| Quote Detail | `/auftrag/${quoteId}` | `/auftrag/1001` | quote, entity |',
+        '| Order List | `/auftrag/bestellung` | `/auftrag/bestellung` | order |',
+        '| New Order | `/auftrag/bestellung/neu` | `/auftrag/bestellung/neu` | order, entity, article |',
+        '| Order Detail | `/auftrag/bestellung/${orderId}` | `/auftrag/bestellung/2005` | order, entity, account, payment, shipping, package |',
+        '| Customer List | `/kunde` | `/kunde` | entity |',
+        '| New Customer | `/kunde/neu` | `/kunde/neu` | entity, customergroup, number |',
+        '| Customer Detail | `/kunde/${entityId}` | `/kunde/312` | entity, customergroup |',
+        '| Customer Groups | `/kunde/gruppen` | `/kunde/gruppen` | customergroup |',
+        '| Article History | `/infos/articlehistory` | `/infos/articlehistory` | article (`GET /article/{sku}/history`) |',
+        '| Global History | `/infos/globalhistory` | `/infos/globalhistory` | company (`GET /company/history`) |',
+        '| Statistics | `/infos/statistics` | `/infos/statistics` | none; aggregate from order, delivery, ledger |',
     ].join('\n');
 
     const sections = [];

src/tools/analyze-image.js

@@ -276,7 +276,7 @@ export function createAnalyzeImageTool({ googleAuthId, model }) {
     return defineTool({
         name: 'analyze_image',
         description:
-            'Inspect 1–9 images via vision model. Multiple paths render as a labelled comparison grid. ' +
+            'Inspect 1-9 images via vision model. Multiple paths render as a labelled comparison grid. ' +
             'Paths: VFS-relative ("images/foo.avif") or DB ("image/<hash>"). Returns model evaluation.',
         strict: false,
         parameters: {
@@ -379,12 +379,12 @@ export function createAnalyzeImageTool({ googleAuthId, model }) {
             const question = typeof prompt === 'string' && prompt.trim() ? prompt.trim() : null;
             const text = items.length > 1
                 ? `${question || 'Compare these images, judge visual quality, flag watermarks, text overlays or defects, and say which one is best and why.'}\n\n` +
-                  `The grid is ${shape.name}. Each image has its file name printed beneath it:\n` +
-                  items.map((it, idx) => {
-                      const row = Math.floor(idx / GRID_CONFIGS[shape.name].cols) + 1;
-                      const col = (idx % GRID_CONFIGS[shape.name].cols) + 1;
-                      return `- Row ${row}, Col ${col}: "${it.name}"`;
-                  }).join('\n')
+                `The grid is ${shape.name}. Each image has its file name printed beneath it:\n` +
+                items.map((it, idx) => {
+                    const row = Math.floor(idx / GRID_CONFIGS[shape.name].cols) + 1;
+                    const col = (idx % GRID_CONFIGS[shape.name].cols) + 1;
+                    return `- Row ${row}, Col ${col}: "${it.name}"`;
+                }).join('\n')
                 : question || 'Describe this image, judge its visual quality, flag any watermark, text overlay or defect, and say whether it is usable as a product or category image.';
 
             const apiKey = await resolveOpenRouterKey(googleAuthId);

src/tools/read-file.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { defineTool, ToolError } from 'libllmorbiter';
 import { isSkillPath, parseSkill, SKILL_EXT } from './skill.js';
+import { getApiRouteSkill } from './routes-skills.js';
 import { prepareVfs } from './vfs.js';
 
 const DEFAULT_LIMIT = 400;
@@ -109,17 +110,18 @@ export function createReadFileTool({ googleAuthId }) {
                 throw new ToolError(`Access denied: path "${filename}" escapes virtual filesystem boundary.`);
             }
 
-            if (!fs.existsSync(absPath)) {
+            const virtualSkill = !fs.existsSync(absPath) && isSkillPath(clean) ? getApiRouteSkill(clean) : null;
+            if (!virtualSkill && !fs.existsSync(absPath)) {
                 throw new ToolError(
                     `File not found in virtual filesystem: "${clean}". ` +
                     'Call find_files to see what is stored, or find_files({ skills: true }) for SKILL files.'
                 );
             }
-            if (!fs.statSync(absPath).isFile()) {
+            if (!virtualSkill && !fs.statSync(absPath).isFile()) {
                 throw new ToolError(`"${clean}" is not a file. Use find_files to list directories.`);
             }
 
-            const raw = fs.readFileSync(absPath);
+            const raw = virtualSkill ? Buffer.from(virtualSkill.content, 'utf8') : fs.readFileSync(absPath);
             if (looksBinary(raw)) {
                 const ext = path.extname(clean).toLowerCase();
                 throw new ToolError(

src/tools/routes-skills.js

@@ -0,0 +1,114 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * routes-skills.js — virtual SKILL files generated from docs/api/routes.md.
+ *
+ * routes.md is split into `### Section: /<segment>` blocks by scripts/generateApiDocs.js. Each
+ * block becomes one in-memory `api-<segment>.SKILL` file (never written to disk), so the model
+ * reads only the routes it needs. Notation and the reusable `Tn` types a section references
+ * (transitively) are inlined so every skill is self-contained.
+ *
+ * Nothing here imports skill.js (skill.js imports this module); the SKILL format is
+ * "title on line 1, blank line, markdown".
+ */
+
+const ROUTES_DOC_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../docs/api/routes.md');
+
+let cache = { mtimeMs: -1, skills: [] };
+
+function slugify(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'root';
+}
+
+function parseRoutesDoc(text) {
+    const lines = text.split('\n');
+    let notation = [];
+    const types = new Map();
+    const sections = [];
+    let mode = null; // 'notation' | 'types' | 'section' | null
+    let current = null;
+
+    for (const line of lines) {
+        const heading = /^### (.*)$/.exec(line);
+        if (heading) {
+            const h = heading[1].trim();
+            current = null;
+            if (h === 'Notation') {
+                mode = 'notation';
+            } else if (h === 'Reusable types') {
+                mode = 'types';
+            } else if (h === 'Routes') {
+                mode = null;
+            } else if (h.startsWith('Section: ')) {
+                const name = h.slice('Section: '.length).trim();
+                current = { slug: slugify(name), title: `API routes: ${name}`, lines: [] };
+                sections.push(current);
+                mode = 'section';
+            } else {
+                const name = h.replace(/\s*\(.*$/, '');
+                current = { slug: slugify(name), title: `API routes: ${name}`, lines: [line] };
+                sections.push(current);
+                mode = 'section';
+            }
+            continue;
+        }
+        if (mode === 'notation') notation.push(line);
+        else if (mode === 'types') {
+            const m = /^- `(T\d+)` = `(.*)`$/.exec(line);
+            if (m) types.set(m[1], m[2]);
+        } else if (mode === 'section' && current) current.lines.push(line);
+    }
+    notation = notation.join('\n').trim();
+    return { notation, types, sections };
+}
+
+function buildSkills(text) {
+    const { notation, types, sections } = parseRoutesDoc(text);
+    return sections.map((section) => {
+        const body = section.lines.join('\n').trim();
+        const used = new Set();
+        const queue = [...body.matchAll(/\bT\d+\b/g)].map((m) => m[0]);
+        while (queue.length) {
+            const id = queue.pop();
+            if (used.has(id) || !types.has(id)) continue;
+            used.add(id);
+            queue.push(...[...types.get(id).matchAll(/\bT\d+\b/g)].map((m) => m[0]));
+        }
+        const typeLines = [...used]
+            .sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)))
+            .map((id) => `- \`${id}\` = \`${types.get(id)}\``);
+
+        const parts = [section.title, '', '### Notation', '', notation];
+        if (typeLines.length) parts.push('', '### Reusable types', '', ...typeLines);
+        parts.push('', '### Routes', '', body, '');
+        return { name: `api-${section.slug}.SKILL`, title: section.title, content: parts.join('\n') };
+    });
+}
+
+/**
+ * Virtual API-route skills, regenerated whenever routes.md changes on disk.
+ * @returns {Array<{ name: string, title: string, content: string }>}
+ */
+export function getApiRouteSkills() {
+    try {
+        const { mtimeMs } = fs.statSync(ROUTES_DOC_PATH);
+        if (mtimeMs !== cache.mtimeMs) {
+            cache = { mtimeMs, skills: buildSkills(fs.readFileSync(ROUTES_DOC_PATH, 'utf8')) };
+        }
+        return cache.skills;
+    } catch (err) {
+        console.error('routes-skills: failed to read routes doc:', err.message);
+        return [];
+    }
+}
+
+/**
+ * @param {string} name bare file name, e.g. `api-article.SKILL`
+ * @returns {{ name: string, title: string, content: string }|null}
+ */
+export function getApiRouteSkill(name) {
+    const lower = String(name).toLowerCase();
+    return getApiRouteSkills().find((s) => s.name.toLowerCase() === lower) || null;
+}

src/tools/skill.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { getApiRouteSkills } from './routes-skills.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -152,6 +153,19 @@ export function readSkillTitle(absPath) {
  * @returns {Array<{ path: string, title: string, lines: number, size: number, updated: string|null }>}
  */
 export function listSkillFiles(vfsRoot) {
+    const out = listDiskSkillFiles(vfsRoot);
+    const onDisk = new Set(out.map((s) => s.path.toLowerCase()));
+    for (const v of getApiRouteSkills()) {
+        if (onDisk.has(v.name.toLowerCase())) continue;
+        const split = v.content.split('\n');
+        if (split[split.length - 1] === '') split.pop();
+        out.push({ path: v.name, title: v.title, lines: split.length, size: Buffer.byteLength(v.content), updated: null, virtual: true });
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+}
+
+function listDiskSkillFiles(vfsRoot) {
     const out = [];
     if (!vfsRoot || !fs.existsSync(vfsRoot)) return out;