docs: add plugin documentation, migration guides, and changesets

VuePress documentation:
- Add top-level plugins section with overview of plugin vs module
  intent and the context-navigation plugin README
- Add context routing strategy migration guide under modules/context
- Update sidebar and theme config for new plugin section

Changesets:
- plugin-context-navigation: initial release (minor)
- module-context: routing strategy addition (minor)
- module-navigation: trailing-slash and basename fix (patch)
- dev-portal: context navigation integration (patch)

Also updates pnpm-lock.yaml for new plugin package dependency.

Author: Noggling

.changeset/fusion-framework-dev-portal_context-navigation-handler.md

@@ -0,0 +1,7 @@
+---
+"@equinor/fusion-framework-dev-portal": patch
+---
+
+Integrate `@equinor/fusion-framework-plugin-context-navigation` into the dev portal.
+
+Portal context-to-URL reconciliation is now handled by `@equinor/fusion-framework-plugin-context-navigation`, replacing the ad-hoc hook-based approach.

.changeset/fusion-framework-module-context_routing-strategy.md

@@ -0,0 +1,20 @@
+---
+"@equinor/fusion-framework-module-context": minor
+---
+
+Add configurable `ContextRoutingStrategy` with `query` and `path` modes for context-aware deep links.
+
+The context module now supports a `routingStrategy` configuration field that controls how context identifiers are written to URLs:
+
+- **`query`** (recommended) — encodes context as the `$contextId` query parameter.
+- **`path`** — encodes context as a path segment (legacy convention).
+
+URL resolution (reading context from a URL) is always query-first: the plugin checks `$contextId` query param first, then falls back to path-segment extraction regardless of the declared strategy.
+
+Apps with custom URL shapes should use `setContextPathExtractor` / `setContextPathGenerator` hooks directly — the context navigation plugin's custom adapter picks up those hooks automatically without requiring a separate strategy value.
+
+The `generatePathFromContext` callback now receives the active `routingStrategy` as a third argument so host integrations can produce strategy-appropriate URLs.
+
+When no strategy is explicitly configured, the module defaults to `path` for backward compatibility and logs a console warning encouraging explicit configuration.
+
+**Deprecations:** `resolveContextFromPath` utilities are deprecated in favour of `@equinor/fusion-framework-plugin-context-navigation`, which handles URL-to-context reconciliation via adapters. `resolveInitialContext` has been simplified to only resolve from the parent context — URL-based resolution is now handled by the plugin. `extractContextIdFromPath` remains supported — it is the default extractor used by `setContextPathExtractor` and the custom adapter fallback.

.changeset/fusion-framework-module-navigation_trailing-slash-fix.md

@@ -0,0 +1,9 @@
+---
+"@equinor/fusion-framework-module-navigation": patch
+---
+
+Fix basename boundary matching and trailing-slash handling.
+
+- `normalizePathname` no longer strips trailing slashes — only collapses consecutive slashes. Trailing slash is now preserved as part of the path identity.
+- `_isWithinBasenameScope` uses a path-boundary check (`pathname === basename || pathname.startsWith(basename + '/')`) to prevent false positives from apps with overlapping name prefixes (e.g. `/apps/my-app` no longer matches `/apps/my-app-other/foo`).
+- `_localizePath` falls back to `'/'` when the basename-stripped pathname is empty.

.changeset/fusion-framework-plugin-context-navigation_initial.md

@@ -0,0 +1,19 @@
+---
+"@equinor/fusion-framework-plugin-context-navigation": minor
+---
+
+Initial release of the context navigation plugin.
+
+Adapter-based, event-driven plugin that reconciles context selection with the browser URL for portal hosts. Ships with built-in adapters for query-param, path-segment, and custom URL shapes, plus two pre-wired source strategies:
+
+- **app-first** — app sets context, the plugin encodes it to the URL.
+- **context-first** — the plugin decodes context from the URL on startup, redirects to a configurable null-context URL when no context is resolvable.
+
+```ts
+import { enableContextNavigation } from '@equinor/fusion-framework-plugin-context-navigation';
+import { createAppFirstSource } from '@equinor/fusion-framework-plugin-context-navigation/sources';
+
+enableContextNavigation(configurator, (builder) => {
+  builder.setSourceFactory(createAppFirstSource());
+});
+```

pnpm-lock.yaml

@@ -451,4 +451,11 @@ export default sidebar({
       ],
     },
   ],
+  '/plugins/': [
+    '',
+    {
+      text: 'Context Navigation',
+      link: 'context-navigation/',
+    },
+  ],
 });

vue-press/src/.vuepress/sidebar.ts

@@ -15,6 +15,10 @@ const navbar: NavbarOptions = [
     text: 'Modules',
     link: '/modules/',
   },
+  {
+    text: 'Plugins',
+    link: '/plugins/',
+  },
   {
     text: 'CLI',
     link: '/cli/',

vue-press/src/.vuepress/theme.ts

@@ -0,0 +1,14 @@
+---
+title: Migration - Context Routing Strategy
+description: Migration guide for adding explicit routing strategy to your app's context module configuration.
+category: Module
+tag:
+  - context
+  - migration
+  - routing-strategy
+  - url
+  - query
+  - path
+---
+
+<!-- @include: ../../../../packages/modules/context/docs/migration-routing-strategy.md -->

vue-press/src/modules/context/migration-routing-strategy.md

@@ -0,0 +1,71 @@
+---
+title: Plugins
+category: Plugin
+tag:
+  - plugins
+  - extension
+  - intent
+---
+
+Plugins extend an existing Fusion Framework host with behavior that is optional, targeted, and intent-driven.
+
+Use this section when you need to answer questions like:
+
+- What is a plugin in Fusion Framework?
+- Why would I use a plugin instead of a module?
+- What behavior does this plugin add to an existing portal or app?
+
+## What Is A Plugin?
+
+A plugin is an add-on that hooks into an already configured Fusion Framework host and contributes one focused behavior.
+
+The key intent is extension, not foundation. A plugin does not usually define a new core runtime capability the way a module does. Instead, a plugin composes with modules that are already present and adds cross-cutting behavior such as URL reconciliation, diagnostics, policy enforcement, or host-specific workflows.
+
+In practice, a plugin is a good fit when the behavior is:
+
+- Optional for the host
+- Focused on one workflow or concern
+- Built on top of existing module instances
+- Easier to enable or disable as a single unit
+
+## Why Use A Plugin?
+
+Use a plugin when you want to capture host intent clearly.
+
+If the host intent is "add this behavior to the portal," a plugin is often the better abstraction than pushing that behavior down into a general-purpose module. That keeps the core module graph smaller and makes the host configuration easier to read.
+
+Plugins are useful because they:
+
+- Make optional behavior explicit in host configuration
+- Keep cross-cutting concerns separate from core modules
+- Encapsulate one integration pattern behind a small enable/configure surface
+- Let portal authors express intent directly: enable this behavior, for this host, with these rules
+
+## Plugin Intent vs Module Intent
+
+Modules and plugins can both affect runtime behavior, but they communicate different intent.
+
+| Surface | Primary intent | Typical role |
+|---|---|---|
+| **Module** | Provide a core capability | State, services, routing, auth, events, telemetry |
+| **Plugin** | Extend a host with focused behavior | Reconciliation, host policies, workflow glue, optional host features |
+
+If your intent is "the framework needs this capability to exist," that usually belongs in a module.
+
+If your intent is "this host should apply this behavior on top of existing capabilities," that usually belongs in a plugin.
+
+## Available Plugins
+
+- [Context Navigation](./context-navigation/)
+
+## Current Plugin
+
+### Context Navigation
+
+The `@equinor/fusion-framework-plugin-context-navigation` package captures a very specific host intent:
+
+keep the browser URL synchronized with the active app context.
+
+It does not replace the context module or navigation module. It composes them. The plugin observes app and context state, chooses the right URL adapter, and applies URL updates consistently for the portal host.
+
+That is a strong plugin fit because the intent is host-level behavior built on top of existing modules rather than a new foundational capability.

vue-press/src/plugins/README.md

@@ -0,0 +1,13 @@
+---
+title: Context Navigation Plugin
+category: Plugin
+tag:
+  - context
+  - navigation
+  - routing
+  - url-sync
+---
+
+<ModuleBadge module="plugins/context-navigation" package="@equinor/fusion-framework-plugin-context-navigation" />
+
+<!-- @include: ../../../../packages/plugins/context-navigation/README.md -->