@lessly/sdk-app 48.0.2 → 48.0.3

package/docs/README.md

@@ -33,9 +33,12 @@ does not apply.
   `X-Product-Id` header — never from a token — and must not implement its own
   auth.
 - **Manifest is `lessly.app.yaml`, schema v1.** Exactly five top-level fields:
-  `app_schema_version: 1`, `id`, `title`, `version`, `nav` (with `nav.icon`).
-  No backend or extension manifest field (`s2s`, `webhooks`, `billing`,
-  `analytics`, `routing`, ...) is valid here.
+  `app_schema_version: 1`, `id`, `title`, `version`, `nav` (`nav.icon`, plus an
+  optional `nav.sections` rail menu). No backend or extension manifest field
+  (`s2s`, `webhooks`, `billing`, `analytics`, `routing`, ...) is valid here.
+- **Your rail menu is manifest data.** The menu the shell draws while your App
+  is open comes from your own `nav.sections` block, not from your App code and
+  not from a toolkit manifest — see APP-011.
 
 ## Quickstart
 
@@ -56,6 +59,9 @@ nav:
   icon: flask
 ```
 
+`nav.sections` — the App's own rail menu — is optional and not scaffolded; add
+it when your App has more than one page (APP-011).
+
 Your app's Module Federation remote exposes a single React component at
 `./App`. The scaffold wires this up for you; see `recipes/federation.md` if
 you need to touch it directly.

package/docs/recipes/federation.md

@@ -28,9 +28,8 @@ There is no `./navigation` module. FED-011 — the shell's extension-menu
 contract — is **RETIRED (2026-08)**: the shell never registers, preloads or
 calls it, there is no `subscribeNavItems` (v1 or v2) and no
 `navContractVersion` negotiation, and the menu the shell renders while your app
-is open comes from the toolkit manifest your App is registered under
-(`nav.sections`, MFST-022 in the toolkit-guide) — your App code does not ship
-it.
+is open comes from **your own** `lessly.app.yaml` — the `nav.sections` block
+(APP-011) — not from your App code, and not from a toolkit manifest.
 
 Still mapping the expose is inert, not an error — you just ship a chunk nobody
 fetches. If your app has one, the cleanup is: delete
@@ -42,6 +41,31 @@ status dots, a settings gear — belongs **in your own pages**, rendered by
 button are unaffected: the dynamic items only ever fed the menu, never the
 router.
 
+## The menu moves to the manifest, not to a module
+
+The rows the module used to publish are now data in your App's manifest:
+
+```yaml
+# lessly.app.yaml
+nav:
+  icon: flask-conical
+  sections:
+    - id: overview
+      items:
+        - label: Dashboard
+          path: ''          # '' = your App's root
+          match: exact
+          icon: gauge
+        - label: Activity
+          path: activity
+          icon: activity
+```
+
+`path` is relative to your App's base path (`/<productSlug>/~/<id>`), so these
+are the same relative routes `./App` already renders under (FED-003). The full
+field constraints, the worked example, what happens when you ship no block, and
+how a change reaches production are in APP-011.
+
 ## Shared singletons: `>=` floors, not carets, on 0.x packages
 
 `react`, `react-dom`, `react-router`, and `@lessly/ui` MUST be declared as

package/docs/rules.md

@@ -33,10 +33,16 @@ service-to-service call, it belongs in an extension, not an App.
 ### APP-003 (MUST) — Manifest is `lessly.app.yaml`, schema v1
 
 The manifest file is `lessly.app.yaml`, and its top-level surface is exactly:
-`app_schema_version: 1`, `id`, `title`, `version`, `nav` (with `nav.icon`). No
-other top-level field is valid — in particular, no extension/backend manifest
-field (`s2s`, `webhooks`, `billing`, `analytics`, `routing`, `public`, ...)
-belongs in an App manifest.
+`app_schema_version: 1`, `id`, `title`, `version`, `nav`. No other top-level
+field is valid — in particular, no extension/backend manifest field (`s2s`,
+`webhooks`, `billing`, `analytics`, `routing`, `public`, ...) belongs in an App
+manifest.
+
+`nav` has exactly two keys: `nav.icon` (**required**, the rail icon) and
+`nav.sections` (**optional**, the App's own rail menu — APP-011). Any other key
+under `nav` is rejected, and rejection is fatal: registration validation is
+whitelist-strict, so an unknown key fails the whole registration rather than
+being stripped.
 
 ### APP-004 (MUST) — Module Federation contract
 
@@ -52,12 +58,11 @@ artifacts (FED-007).
 `./App` is the **only** module an App exposes. There is no `./navigation`
 contract: the shell no longer loads such a module, there is no
 `subscribeNavItems` and no `navContractVersion` negotiation, and the menu the
-shell renders comes from the toolkit manifest your App is registered under
-(`nav.sections`, MFST-022 in the toolkit-guide) — your App code does not ship
-it. FED-011 is **RETIRED (2026-08)**. Still mapping the expose is inert rather
-than an error — it just ships a chunk nobody fetches — but a new App MUST NOT
-add it, and an existing
-one SHOULD delete `src/federation/navigation.ts`, drop the expose, and move
+shell renders comes from **your own** `lessly.app.yaml` — the `nav.sections`
+block (APP-011) — not from your App code, and not from a toolkit manifest.
+FED-011 is **RETIRED (2026-08)**. Still mapping the expose is inert rather than
+an error — it just ships a chunk nobody fetches — but a new App MUST NOT add
+it, and an existing one SHOULD delete `src/federation/navigation.ts`, drop the expose, and move
 whatever that module fed the menu (environment lists, tool groups, badges,
 status dots, a settings gear) into its own pages under `./App`'s relative
 routes (FED-003).
@@ -235,3 +240,81 @@ See FED-014 in the toolkit-guide for the measurement (App `.px-2` against
 shell `.sm:px-2.5` — different rule names, so no shared preset can reach them;
 5 of 283 shell chrome nodes affected) and for the accepted symmetric risk on
 the App's own nodes.
+
+### APP-011 (SHOULD) — Declare the rail menu in your own manifest
+
+The rail menu the shell draws while your App is open comes from your App's own
+`lessly.app.yaml`, in an optional `nav.sections` block. An App with more than
+one page SHOULD declare it; without it the shell has nothing of yours to draw
+(see *No block* below).
+
+```yaml
+app_schema_version: 1
+id: my-app
+title: My App
+version: 0.2.0
+nav:
+  icon: flask-conical
+  sections:
+    - id: overview
+      items:
+        - label: Dashboard
+          path: ''
+          match: exact
+          icon: gauge
+        - label: Activity
+          path: activity
+          icon: activity
+    - id: settings
+      header: Settings
+      items:
+        - label: Members
+          path: settings/members
+          icon: users-round
+        - label: API keys
+          path: settings/api-keys
+          icon: key
+```
+
+**Field constraints.** These are validated on registration by the platform's
+shared `NavSectionDto`/`NavItemDto` — literally the same DTO classes the
+toolkit manifest validates against (MFST-022 in the toolkit-guide), so the two
+manifests speak exactly one menu language. A violation is a hard reject of the
+registration, not a silent strip.
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `nav.sections` | no | array, 1–20 sections; `id` unique across the array |
+| `sections[].id` | yes | 1–50 chars, lowercase-kebab `^[a-z0-9-]+$` |
+| `sections[].header` | no | 1–50 chars; absent → the group renders with no header line |
+| `sections[].items` | yes | array, 1–50 items |
+| `items[].label` | yes | 1–50 chars, non-empty |
+| `items[].path` | yes | 0–200 chars, `^[a-z0-9-_/]*$`, **no leading slash**, no `..` segment; `''` = your tool root |
+| `items[].icon` | no | 1–50 chars, kebab-case Lucide icon name (e.g. `rocket`) |
+| `items[].match` | no | `exact` or `prefix`; default `prefix` |
+
+`path` is relative to your App's own base path (`/<productSlug>/~/<id>`), so a
+manifest can name a page **inside** your App and nothing else — no absolute
+paths, no external URLs, no traversal. Use `match: exact` on a row whose path
+is a prefix of a sibling's (typically the `''` root row), or it stays lit while
+the sibling is open.
+
+**No block.** `nav.sections` absent is legal. The shell then falls back to its
+transitional table (`extension-menus.ts`, keyed by slug, entity-agnostic) if
+your slug is listed there; if it is not, your rail row stays a **single plain
+link** into the App, with no disclosure mark promising rows that do not exist.
+The fallback is transitional: an App leaves that table the moment its manifest
+ships the menu, and the entry there should be deleted by the same PR. Narrowing
+of the served block is **all-or-nothing** — a half-valid menu falls back to the
+table rather than drawing a partial disclosure.
+
+**Shipping a change.** The menu is picked up on re-registration, including a
+**same-version** one: the registration overlay replaces the whole `nav` blob,
+so adding, editing and removing sections all land without a `version` bump.
+Bumping `version` on release remains APP-007.
+
+**The scaffold's linter does not check this block.** `create-lessly-app lint`
+validates the top-level surface and `nav.icon` only; it neither rejects nor
+warns on `nav.sections`, and it will not catch a malformed one. The platform's
+registration validation is the authority — a menu that lints clean locally can
+still fail registration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "48.0.2",
+  "version": "48.0.3",
   "type": "module",
   "sideEffects": false,
   "engines": {