@proveanything/smartlinks 1.6.6 → 1.7.0

package/dist/docs/deep-link-discovery.md

@@ -26,113 +26,112 @@ Complete guide to registering and discovering navigable states in SmartLinks app
 
 ## Overview
 
-SmartLinks apps can expose **deep-linkable states** — specific views, pages, or configurations that other apps, the portal, or AI orchestrators can navigate to directly without loading the app first.
+SmartLinks apps expose **deep-linkable states** — specific views, pages, or configurations that the portal, AI orchestrators, or other apps can navigate to directly without loading the app first.
 
-This is done by publishing a `linkable` array in the app's `appConfig`. Any consumer (portal shell, AI agent, another app) can read this array to discover what navigable states the app currently offers.
+Deep-linkable states come from **two sources** depending on their nature:
+
+| Source | What goes here | When it changes |
+|--------|---------------|-----------------|
+| **App manifest** (`app.manifest.json`) | Fixed routes built into the app | Only when the app itself is updated |
+| **App config** (`appConfig.linkable`) | Content-driven entries that vary by collection | When admins create, remove, or rename content |
+
+Consumers merge both sources to get the full set of navigable states for an app.
 
 ```text
-┌─────────────────────────────────────────────────────────────────────┐
-│ Your SmartLinks App                                                  │
-│                                                                      │
-│  ┌───────────────────────┐     writes     ┌────────────────────────┐│
-│  │  Admin / Data Events  │ ─────────────► │   appConfig.linkable   ││
-│  └───────────────────────┘                └────────────────────────┘│
-└─────────────────────────────────────────────────────────────────────┘
-                                                       │
-                                          reads linkable[]
-                                                       │
-                   ┌───────────────────────────────────┼───────────────────────┐
-                   ▼                                   ▼                       ▼
-        ┌─────────────────────┐           ┌────────────────────┐   ┌─────────────────────┐
-        │  Portal Nav Menu    │           │   AI Orchestrator  │   │    Another App      │
-        │  (sidebar / drawer) │           │  ("Go to About Us")│   │  (cross-app nav)    │
-        └─────────────────────┘           └────────────────────┘   └─────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────┐
+│ App Definition (build time)                                              │
+│  app.manifest.json → "linkable": [                                       │
+│    { "title": "Gallery",  "path": "/gallery" },                          │
+│    { "title": "Settings", "path": "/settings" }                          │
+│  ]                                                                       │
+└──────────────────────────────────────┬──────────────────────────────────┘
+                                       │  static (always present)
+                                       ▼
+                          ┌────────────────────────┐
+                          │   merged linkable[]    │◄──── dynamic (per collection)
+                          └────────────────────────┘
+                                       ▲
+┌──────────────────────────────────────┴──────────────────────────────────┐
+│ App Config (runtime, per collection)                                     │
+│  appConfig.linkable = [                                                  │
+│    { "title": "About Us",   "params": { "pageId": "about-us" } },        │
+│    { "title": "FAQ",        "params": { "pageId": "faq" } }              │
+│  ]                                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
 ```
 
 ### Key Benefits
 
 - ✅ **Discoverable** — consumers don't need to know the app's internal routing
-- ✅ **Decoupled** — the app owns the registry; consumers just read it
-- ✅ **Dynamic** — the registry updates automatically when content changes
+- ✅ **No first-run initialisation** — static routes are available from the moment the app is installed
+- ✅ **Dynamic** — content-driven entries update automatically when data changes
 - ✅ **AI-friendly** — machine-readable titles make states naturally addressable by LLMs
-- ✅ **No extra endpoints** — built on top of the existing `appConfiguration` API
+- ✅ **No extra endpoints** — built on top of the existing `appConfiguration` API and the app manifest
 
 ---
 
-## Quick Start
+## Two Sources of Truth
 
-**App side — publish linkable states:**
+### Static Links — App Manifest
 
-```typescript
-import { appConfiguration } from '@proveanything/smartlinks';
+Static links are routes that are **built into the app itself** — they exist regardless of what content admins have created. They belong in `app.manifest.json` as a top-level `linkable` array, as a peer to `widgets` and `containers`:
 
-await appConfiguration.setConfig({
-  collectionId,
-  appId,
-  config: {
-    // ... other app config ...
-    linkable: [
-      { title: 'Gallery', path: '/gallery' },
-      { title: 'About Us', params: { pageId: 'about-us' } },
-      { title: 'FAQ', params: { pageId: 'faq' } },
-    ]
-  },
-  admin: true
-});
+```json
+{
+  "linkable": [
+    { "title": "Gallery",           "path": "/gallery" },
+    { "title": "Settings",          "path": "/settings" },
+    { "title": "Advanced Settings", "path": "/settings", "params": { "tab": "advanced" } }
+  ],
+  "setup": { }
+}
 ```
 
-**Consumer side — read linkable states:**
-
-```typescript
-import { appConfiguration } from '@proveanything/smartlinks';
-
-const config = await appConfiguration.getConfig({ collectionId, appId });
-const linkable = config?.linkable ?? [];
+**Use this for:**
+- Named sections or tabs that are always present in the app
+- Admin-accessible pages that exist at fixed routes
+- Any navigable state whose existence doesn't depend on content
 
-// linkable = [
-//   { title: 'Gallery', path: '/gallery' },
-//   { title: 'About Us', params: { pageId: 'about-us' } },
-//   { title: 'FAQ', params: { pageId: 'faq' } },
-// ]
-```
+**Why manifest, not config?**
+These routes are part of the app's *definition*, not its *runtime state*. Putting them in the manifest means they're immediately available the moment the app is installed — no first-run initialisation, no sync step, no risk of them being missing if the app has never been launched.
 
 ---
 
-## The `linkable` Registry
-
-Each app **MAY** store a `linkable` array at the top level of its `appConfig`. This array describes all the deep-linkable states the app currently exposes.
+### Dynamic Links — App Config
 
-### Storage Location
-
-The `linkable` key is **reserved** at the top level of `appConfig` for this purpose. Do not use it for anything else.
+Dynamic links are entries **generated from content** — CMS pages, product guides, FAQ items, or anything else that admins create and manage. These are stored at `appConfig.linkable` and updated whenever the content changes:
 
 ```typescript
-// Writing
+import { appConfiguration } from '@proveanything/smartlinks';
+
 await appConfiguration.setConfig({
   collectionId,
   appId,
   config: {
     // ... other app config ...
-    linkable: [ /* DeepLinkEntry[] */ ]
+    linkable: [
+      { title: 'About Us',   params: { pageId: 'about-us' } },
+      { title: 'Care Guide', params: { pageId: 'care-guide' } },
+      { title: 'FAQ',        params: { pageId: 'faq' } },
+    ]
   },
   admin: true
 });
-
-// Reading
-const config = await appConfiguration.getConfig({ collectionId, appId });
-const linkable: DeepLinkEntry[] = config?.linkable ?? [];
 ```
 
-### Admin vs Public Access
+**Use this for:**
+- Pages or content entries created by admins that should be directly navigable
+- Any set of linkable states that varies between collections or changes over time
 
-- **Writing** always requires `admin: true` — only the app itself (running with admin credentials) should update its own registry.
-- **Reading** can be done publicly — portals and consumers typically read the registry without admin credentials.
+The `linkable` key is **reserved** at the top level of `appConfig` for this purpose.
+
+> **`appConfig.linkable` is for dynamic content only.** Static routes belong in the manifest. Don't write fixed routes to `appConfig` on first install just to make them discoverable — that's the problem this split is designed to avoid.
 
 ---
 
 ## Schema: DeepLinkEntry
 
-Each entry in the `linkable` array describes one navigable state:
+Both sources use the same entry shape:
 
 ```typescript
 interface DeepLinkEntry {
@@ -159,65 +158,63 @@ interface DeepLinkEntry {
 }
 ```
 
-### Field Notes
-
 | Field | Required | Notes |
 |-------|----------|-------|
 | `title` | ✅ | Displayed in menus and offered to AI agents. Should be concise and human-readable. |
 | `path` | ❌ | Hash route within the app. Defaults to `/` if omitted. |
 | `params` | ❌ | App-specific query params only. Platform params are injected automatically. |
 
-> **Tip:** An entry with only a `title` (no `path` or `params`) is valid — it navigates to the app's default view. This is rarely useful unless the app's home screen is itself a meaningful destination distinct from other entries.
+> **Tip:** Different entries can share the same `path` if they differ by `params` — for example, two entries pointing at `/settings` with different `tab` params.
 
 ---
 
-## Entry Types
-
-### 1. Data-Driven Entries (Dynamic)
+## Quick Start
 
-Generated from app data — e.g., CMS pages, product guides, FAQ items. These are typically re-synced whenever the underlying data changes.
+**An app with both static routes and dynamic content pages:**
 
+`app.manifest.json` — declare static routes once, at build time:
 ```json
-[
-  { "title": "About Us",   "params": { "pageId": "about-us" } },
-  { "title": "Care Guide", "params": { "pageId": "care-guide" } },
-  { "title": "FAQ",        "params": { "pageId": "faq" } }
-]
+{
+  "linkable": [
+    { "title": "Gallery",  "path": "/gallery" },
+    { "title": "Settings", "path": "/settings" }
+  ]
+}
 ```
 
-**When to use:** The set of linkable states depends on admin-created content. The registry is rebuilt whenever pages are added, removed, published, or renamed.
-
-### 2. Route-Based Entries (Static)
+App code — sync dynamic content entries whenever pages change:
+```typescript
+import { appConfiguration } from '@proveanything/smartlinks';
 
-Fixed routes that are built into the app. Declared once and rarely change.
+async function syncDynamicLinks(collectionId: string, appId: string): Promise<void> {
+  // Always fetch fresh data — never rely on cache
+  const pages = await myApi.getPublishedPages({ forceRefresh: true });
+  const entries = pages
+    .filter(p => p.deepLinkable)
+    .map(p => ({ title: p.title, params: { pageId: p.slug } }));
 
-```json
-[
-  { "title": "Gallery",             "path": "/gallery" },
-  { "title": "Settings",            "path": "/settings" },
-  { "title": "Advanced Settings",   "path": "/settings", "params": { "tab": "advanced" } }
-]
+  const config = await appConfiguration.getConfig({ collectionId, appId, admin: true }) ?? {};
+  await appConfiguration.setConfig({
+    collectionId, appId,
+    config: { ...config, linkable: entries },
+    admin: true,
+  });
+}
 ```
 
-**When to use:** The app has multiple built-in views (tabs, sections) that should always be directly navigable, regardless of content.
-
-> **Note:** Different entries can share the same `path` if they differ by `params` — as in the Settings example above.
-
-### 3. Mixed
+Consumer — merge both sources:
+```typescript
+// staticLinks come from the app's manifest (loaded by the platform when the app was registered)
+const staticLinks: DeepLinkEntry[] = appManifest?.linkable ?? [];
 
-Apps can freely combine both patterns. Static routes can appear alongside dynamic content entries:
+// dynamicLinks come from appConfig (per-collection, fetched at runtime)
+const config = await appConfiguration.getConfig({ collectionId, appId });
+const dynamicLinks: DeepLinkEntry[] = config?.linkable ?? [];
 
-```json
-[
-  { "title": "Gallery",    "path": "/gallery" },
-  { "title": "About Us",   "params": { "pageId": "about-us" } },
-  { "title": "FAQ",        "params": { "pageId": "faq" } },
-  { "title": "Settings",   "path": "/settings" }
-]
+// Full set — static (structural) first, then dynamic (content)
+const allLinks = [...staticLinks, ...dynamicLinks];
 ```
 
-**Ordering:** Entries are displayed in array order. Place the most commonly navigated states first.
-
 ---
 
 ## URL Resolution
@@ -254,16 +251,17 @@ The platform automatically injects the following — **never include these in `p
 
 ---
 
-## Syncing the Registry
+## Syncing Dynamic Links
+
+This section only applies to **dynamic links stored in `appConfig.linkable`**. Static links declared in the manifest require no syncing.
 
 ### When to Sync
 
-Apps **MUST** update the `linkable` array whenever the set of navigable states changes:
+Apps **MUST** update `appConfig.linkable` whenever the set of dynamic navigable states changes:
 
 - A page is created, deleted, published, or unpublished
 - A page's `deepLinkable` flag is toggled
 - A page title changes
-- App routes are added or removed
 
 ### How to Sync
 
@@ -273,9 +271,9 @@ The sync pattern is a **full replace** — read current config, overwrite `linka
 import { appConfiguration } from '@proveanything/smartlinks';
 
 async function syncLinkable(collectionId: string, appId: string): Promise<void> {
-  // 1. Fetch the current set of linkable states from your data source
-  //    Always fetch fresh — never rely on a local cache
-  const entries = await fetchLinkableEntries(); // your app-specific logic
+  // 1. Fetch the current set of dynamic entries from your data source.
+  //    Always fetch fresh — never rely on a local cache.
+  const entries = await fetchDynamicLinkEntries(); // app-specific
 
   // 2. Read the existing appConfig to preserve other keys
   let config: Record<string, unknown> = {};
@@ -289,7 +287,7 @@ async function syncLinkable(collectionId: string, appId: string): Promise<void>
     // Config may not exist yet on first run — that's fine
   }
 
-  // 3. Merge and save
+  // 3. Overwrite only the linkable key and save
   await appConfiguration.setConfig({
     collectionId,
     appId,
@@ -299,42 +297,13 @@ async function syncLinkable(collectionId: string, appId: string): Promise<void>
 }
 ```
 
-### What `fetchLinkableEntries` looks like
-
-This function is app-specific. A typical CMS app might look like:
-
-```typescript
-async function fetchLinkableEntries(): Promise<DeepLinkEntry[]> {
-  // Fetch your pages/content from the server (not from cache)
-  const pages = await myApi.getPublishedPages({ forceRefresh: true });
-
-  return pages
-    .filter(page => page.deepLinkable)
-    .map(page => ({
-      title: page.title,
-      params: { pageId: page.slug },
-    }));
-}
-```
-
-A route-based app simply returns a static array:
-
-```typescript
-async function fetchLinkableEntries(): Promise<DeepLinkEntry[]> {
-  return [
-    { title: 'Gallery', path: '/gallery' },
-    { title: 'Settings', path: '/settings' },
-  ];
-}
-```
-
 ### Idempotency
 
 The sync is always a full replace of the `linkable` array. Running it multiple times with the same data produces the same result — no duplicates, no orphans.
 
-### Clearing the Registry
+### Clearing Dynamic Links
 
-To remove all linkable states (e.g., when an app is deactivated):
+To remove all dynamic entries (e.g., all content was unpublished):
 
 ```typescript
 await appConfiguration.setConfig({
@@ -345,13 +314,48 @@ await appConfiguration.setConfig({
 });
 ```
 
+Note that clearing `appConfig.linkable` only removes dynamic entries. Static links declared in the manifest are unaffected.
+
 ---
 
 ## Consumer Patterns
 
+### Merging Both Sources
+
+Consumers must always merge static (manifest) and dynamic (appConfig) entries. The platform provides the manifest when the app is registered; the consumer fetches the config at runtime:
+
+```typescript
+import { appConfiguration } from '@proveanything/smartlinks';
+
+interface ResolvedLink extends DeepLinkEntry {
+  appId: string;
+  source: 'manifest' | 'config';
+}
+
+async function getAppLinks(
+  collectionId: string,
+  appId: string,
+  appManifest: { linkable?: DeepLinkEntry[] }
+): Promise<ResolvedLink[]> {
+  // Static entries from the manifest — always present, no network call needed
+  const staticLinks = (appManifest.linkable ?? []).map(e => ({
+    ...e, appId, source: 'manifest' as const
+  }));
+
+  // Dynamic entries from appConfig — vary per collection
+  const config = await appConfiguration.getConfig({ collectionId, appId });
+  const dynamicLinks = (config?.linkable ?? []).map(e => ({
+    ...e, appId, source: 'config' as const
+  }));
+
+  // Static first (fixed structure), then dynamic (content entries)
+  return [...staticLinks, ...dynamicLinks];
+}
+```
+
 ### Portal Navigation Menu
 
-A portal shell can aggregate linkable states from all apps in a collection to build a unified navigation menu:
+A portal shell aggregates links from all installed apps to build a unified navigation menu:
 
 ```typescript
 import { appConfiguration } from '@proveanything/smartlinks';
@@ -363,15 +367,22 @@ interface NavLink {
   params?: Record<string, string>;
 }
 
-async function buildNavMenu(collectionId: string, appIds: string[]): Promise<NavLink[]> {
+async function buildNavMenu(
+  collectionId: string,
+  apps: Array<{ appId: string; manifest: { linkable?: DeepLinkEntry[] } }>
+): Promise<NavLink[]> {
   const links: NavLink[] = [];
 
-  for (const appId of appIds) {
+  for (const { appId, manifest } of apps) {
+    // Static links from manifest
+    const staticLinks = manifest.linkable ?? [];
+
+    // Dynamic links from appConfig
     const config = await appConfiguration.getConfig({ collectionId, appId });
-    const entries: DeepLinkEntry[] = config?.linkable ?? [];
+    const dynamicLinks: DeepLinkEntry[] = config?.linkable ?? [];
 
     links.push(
-      ...entries.map(entry => ({ ...entry, appId }))
+      ...[...staticLinks, ...dynamicLinks].map(entry => ({ ...entry, appId }))
     );
   }
 
@@ -381,19 +392,22 @@ async function buildNavMenu(collectionId: string, appIds: string[]): Promise<Nav
 
 ### AI Orchestration
 
-An AI agent can discover what states an app exposes and offer navigation as part of a conversation:
+An AI agent discovers all navigable states and offers them to the user:
 
 ```typescript
 import { appConfiguration } from '@proveanything/smartlinks';
 
-async function getNavigationOptions(collectionId: string, appId: string) {
+async function getNavigationOptions(
+  collectionId: string,
+  appId: string,
+  appManifest: { linkable?: DeepLinkEntry[] }
+): Promise<string[]> {
+  const staticLinks = appManifest.linkable ?? [];
   const config = await appConfiguration.getConfig({ collectionId, appId });
-  const linkable: DeepLinkEntry[] = config?.linkable ?? [];
+  const dynamicLinks: DeepLinkEntry[] = config?.linkable ?? [];
 
-  // The AI now knows what's available:
-  // "I can navigate you to: Gallery, About Us, or FAQ.
-  //  Which would you prefer?"
-  return linkable.map(entry => entry.title);
+  // "I can navigate you to: Gallery, Settings, About Us, or FAQ."
+  return [...staticLinks, ...dynamicLinks].map(entry => entry.title);
 }
 ```
 
@@ -401,16 +415,15 @@ The `title` field is intentionally human-readable so it can be injected directly
 
 ### Cross-App Navigation
 
-An app can use another app's `linkable` registry to construct a `NavigationRequest` for the portal's `onNavigate` callback:
+An app constructs a `NavigationRequest` using the target app's merged links:
 
 ```typescript
-// Inside a widget or container's onNavigate handler
-const targetConfig = await appConfiguration.getConfig({
-  collectionId,
-  appId: 'target-app-id',
-});
+// Search static links first, then dynamic
+const staticEntry = targetManifest?.linkable?.find(e => e.title === 'Gallery');
+const config = await appConfiguration.getConfig({ collectionId, appId: 'target-app-id' });
+const dynamicEntry = config?.linkable?.find(e => e.title === 'About Us');
 
-const entry = targetConfig?.linkable?.find(e => e.title === 'About Us');
+const entry = staticEntry ?? dynamicEntry;
 
 if (entry) {
   onNavigate({
@@ -423,51 +436,12 @@ if (entry) {
 
 ---
 
-## Manifest Declaration
-
-Apps that support deep linking **SHOULD** declare the `linkable` key in their `app.admin.json` config schema. This signals to platform tooling that the key is auto-managed and prevents accidental manual edits:
-
-```json
-{
-  "setup": {
-    "configSchema": {
-      "properties": {
-        "linkable": {
-          "type": "array",
-          "description": "Auto-managed deep link registry. Do not edit manually.",
-          "readOnly": true,
-          "items": {
-            "type": "object",
-            "required": ["title"],
-            "properties": {
-              "title":  { "type": "string", "description": "Human-readable label" },
-              "path":   { "type": "string", "description": "Hash route path, e.g. '/gallery'" },
-              "params": {
-                "type": "object",
-                "description": "App-specific query params. Do not include platform context params.",
-                "additionalProperties": { "type": "string" }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-> **Note:** The `readOnly: true` flag is a hint to the admin UI to hide or disable this field in manual config editors.
-
----
-
 ## TypeScript Types
 
-Copy these types into your app, or import them if they become part of the SDK's public API:
-
 ```typescript
 /**
  * A single navigable state exposed by a SmartLinks app.
- * Stored as an array at `appConfig.linkable`.
+ * Used in both app.manifest.json `linkable` (static) and appConfig `linkable` (dynamic).
  */
 export interface DeepLinkEntry {
   /** Human-readable label shown in menus and offered to AI agents */
@@ -485,10 +459,7 @@ export interface DeepLinkEntry {
   params?: Record<string, string>;
 }
 
-/**
- * The shape of the `linkable` key in appConfig.
- * Alias for convenience.
- */
+/** Convenience alias for an array of DeepLinkEntry */
 export type DeepLinkRegistry = DeepLinkEntry[];
 ```
 
@@ -498,17 +469,20 @@ export type DeepLinkRegistry = DeepLinkEntry[];
 
 ### Rules
 
-1. **`linkable` is reserved** — do not use this key for other purposes in `appConfig`.
-2. **No platform context params in entries** — `collectionId`, `appId`, `productId`, `proofId`, `lang`, `theme` are injected by the platform automatically.
-3. **`title` is required** — every entry must have a human-readable label.
-4. **Sync from server** — always fetch fresh data when syncing; never read from a local cache or previously fetched state.
-5. **Full replace** — always overwrite the entire `linkable` array; never attempt to diff or patch individual entries.
+1. **Static routes belong in the manifest** — if a route exists regardless of content, declare it in `app.manifest.json`. Do not write it to `appConfig` on first run.
+2. **`appConfig.linkable` is for dynamic content only** — it should contain entries generated from, and varying with, the app's data.
+3. **`linkable` is reserved** — do not use this key for other purposes in either the manifest or `appConfig`.
+4. **No platform context params in entries** — `collectionId`, `appId`, `productId`, `proofId`, `lang`, `theme` are injected by the platform automatically.
+5. **`title` is required** — every entry must have a human-readable label.
+6. **Consumers must merge both sources** — never assume all links come from `appConfig` alone.
+7. **Sync from server** — when updating `appConfig.linkable`, always fetch the latest content state; never rely on a local cache.
+8. **Full replace** — always overwrite the entire `appConfig.linkable` array; never diff or patch individual entries.
 
 ### Best Practices
 
 - **Keep titles short and scannable** — they appear in navigation menus and AI prompts. Prefer "About Us" over "Our Company Story & Mission".
-- **Order entries by relevance** — the first few entries are most likely to be shown in compact menus; place the most important states first.
-- **Sync eagerly** — trigger a sync immediately after any content change rather than on a schedule. The operation is cheap and idempotent.
-- **Handle missing `linkable` gracefully** — older apps won't have a `linkable` key. Always use `config?.linkable ?? []` rather than `config.linkable`.
-- **Don't duplicate the default route** — if your app has only one view, an empty `linkable` array (or omitting it) is better than a single entry that just opens the app.
-- **Test URL resolution** — confirm that your entries produce the correct URLs in the platform before publishing. Check that params are correctly appended and context params are not doubled up.
+- **Static first, dynamic second** — when rendering merged links, show static (structural) entries before dynamic (content) entries. This provides a consistent layout even while content is loading.
+- **Sync dynamic links eagerly** — trigger a sync immediately after any content change rather than on a schedule. The operation is cheap and idempotent.
+- **Handle missing entries gracefully** — older apps won't have manifest `linkable` entries or `appConfig.linkable`. Always use `?? []` on both sources.
+- **Don't duplicate the default route** — if your app has only one view, neither source needs a `linkable` entry for it. The app can always be opened to its default state without a deep link.
+- **Test URL resolution** — confirm that your entries produce the correct URLs. Check that params are correctly appended and that platform context params are not doubled up.