@equinor/fusion-framework-cli 11.0.0-next.7 → 11.0.0

package/CHANGELOG.md

@@ -1,135 +1,98 @@
 # Change Log
 
-## 11.0.0-next.7
+## 11.0.0
 
-### Patch Changes
-
-- Updated dependencies []:
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.2
-  - @equinor/fusion-framework-dev-server@1.0.0-next.4
-
-## 11.0.0-next.6
-
-### Minor Changes
+### Major Changes
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`87bfb21`](https://github.com/equinor/fusion-framework/commit/87bfb21c588a434b574b8cd408bb5dc2642f0974) Thanks [@odinr](https://github.com/odinr)! - improve help output for all commands
+- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253) Thanks [@odinr](https://github.com/odinr)! - **Major Changes**
 
-  - All CLI commands now provide more detailed and consistent help output, including arguments, options, and usage examples.
-  - Updated descriptions and help text for all app, portal, and auth commands to improve discoverability and onboarding.
+  - **Rewrite:** The CLI has been rewritten to use Fusion Framework internally, minimizing dependencies and improving performance. It is now a first-class citizen in the Fusion Framework ecosystem, providing a more consistent and integrated experience.
+  - **Dev Portal Modularization:** The dev portal has been moved to a separate package `@equinor/fusion-framework-dev-server`, enabling modular architecture and independent updates. The dev portal can be configured via `dev-server.config.js` and supports live preview and API mocking.
+  - **Command Structure:** CLI is now divided into three main groups: `bin` (executable functions), `commands` (CLI commands), and `lib` (for consumers, config, and utilities). This improves organization and modularity.
+  - **BREAKING:** The `--service` flag has been removed. The CLI now uses service discovery via Fusion environment variables. All `app -build-???` commands are deprecated and will be removed in the next major version.
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`c4cb2f7`](https://github.com/equinor/fusion-framework/commit/c4cb2f798d9804438bc216096cf4089097b3d31c) Thanks [@odinr](https://github.com/odinr)! - cli: add portal config support
+  - **Dev Server Abstraction:** Vite configuration and dev server functionality has been abstracted into the `@equinor/fusion-framework-dev-server` package. The CLI now provides a higher-level API that handles Vite configuration internally, eliminating the need for users to manage Vite configuration directly while still allowing for customization through configuration options.
 
-  - Added support for loading and resolving portal configuration files via `loadPortalConfig` and `resolvePortalConfig` helpers.
-  - Introduced `PortalConfig`, `PortalConfigFn`, and `definePortalConfig` types/utilities for authoring static or dynamic portal configs.
-  - Updated dev server logic to use resolved portal config.
-  - Exposed new config utilities from `lib/portal` index.
+  - **New Utility Functions:** The CLI now includes new utility modules for resolving CI/CD metadata (GitHub Actions, Azure DevOps), git commit and remote info, and package metadata. These utilities support advanced scripting and automation scenarios.
 
-  This enables flexible, type-safe portal configuration for local development and deployment scenarios.
+  **Minor Changes**
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`b8ed76f`](https://github.com/equinor/fusion-framework/commit/b8ed76f3a6d89b89315c58ec7743f5b0b7303371) Thanks [@odinr](https://github.com/odinr)! - Added alias for fusion-framework-cli to ffc
+  - **Portal Config Support:** Added helpers for loading and resolving portal configuration files, with new types and utilities for authoring static or dynamic portal configs. Dev server logic updated to use resolved portal config.
+  - **Manifest Refactor:** Portal manifest now uses `name` and `templateEntry` for consistency with app manifests. Dev server config and routing updated. Asset paths now use `/@fs` for local development. Improved type safety and schema validation.
+  - **ESM Modernization:** Refactored CLI to use deepmerge instead of lodash.mergewith, updated all imports to use explicit `.js` extensions, and re-exported all bin entrypoints for ESM compatibility. Updated package.json and tsconfig.json for ESM.
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`7b8aca4`](https://github.com/equinor/fusion-framework/commit/7b8aca443197791053da20f3b43784ec69f3f4b7) Thanks [@odinr](https://github.com/odinr)! - - Added a new command to the CLI for managing portal configuration.
-  - This update introduces enhanced support for portal config operations via the `@equinor/fusion-framework-cli` package.
+  **Patch Changes**
 
-## 11.0.0-next.5
+  - **Dev Server Config:** Refactored config loading and merging, added `RecursivePartial` type, custom array merge strategy, and improved documentation. Arrays of route objects are now merged by `match` property to ensure uniqueness.
+  - **Node Version Check:** Added Node.js version check and LTS recommendation to CLI entrypoint. Build config injects version info via environment variables.
 
-### Minor Changes
+  **Other**
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`a3ce07a`](https://github.com/equinor/fusion-framework/commit/a3ce07a367ae8d5a6dbac438c25928df54aefecf) Thanks [@odinr](https://github.com/odinr)! - - Portal manifest now uses `name` (unscoped) and `templateEntry` instead of `id` and `entrypoint` for improved consistency with app manifests.
+  - Improved maintainability, type safety, and developer experience throughout the CLI and dev server packages.
 
-  - Dev server configuration and routing updated to expect and utilize the new manifest structure.
-  - Asset paths for development and preview builds now use `/@fs` for more reliable local development.
-  - Type safety and schema validation for portal manifests have been improved.
-  - Minor typos fixed and comments clarified throughout related files.
+  **Note:**
 
-  This refactor unifies manifest handling between apps and portals, simplifies local development, and ensures better type safety and validation. It also improves maintainability and developer experience by making configuration more predictable and robust.
+  - The removal of Vite config and schema utilities is a breaking change for users who previously relied on CLI-provided defaults. Please migrate to custom configuration as needed.
+  - The new utility modules are available for advanced use cases and automation, but do not affect most standard CLI usage.
+  - If you are authoring an `app.config.ts` file, you now need to import the config helper as follows:
 
-### Patch Changes
+    ```diff
+    -import { defineAppConfig } from '@equinor/fusion-framework-cli';
+    +import { defineAppConfig } from '@equinor/fusion-framework-cli/app';
+    ```
 
-- Updated dependencies [[`2ed792a`](https://github.com/equinor/fusion-framework/commit/2ed792a1118f3726f811c4dbdf8d25c69d7bb756), [`d9a7ada`](https://github.com/equinor/fusion-framework/commit/d9a7ada786bfac3a0714f38c1379b5aac09a0f71)]:
-  - @equinor/fusion-framework-dev-server@1.0.0-next.3
-  - @equinor/fusion-imports@1.1.1-next.0
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.2
+  **Further Reading & Documentation Highlights**
 
-## 11.0.0-next.4
+  +- See the CLI's [README](https://github.com/equinor/fusion-framework/blob/main/packages/cli/README.md) for a full overview, installation, and command reference.
+  +- The [docs folder](https://github.com/equinor/fusion-framework/tree/main/packages/cli/docs) contains:
 
-### Patch Changes
+  - - [Developing Apps](https://github.com/equinor/fusion-framework/blob/main/packages/cli/docs/application.md): Step-by-step guide to app setup, config, CI/CD, and best practices.
+  - - [Developing Portals](https://github.com/equinor/fusion-framework/blob/main/packages/cli/docs/portal.md): Portal template development, manifest/schema, and deployment.
+  - - [Authentication](https://github.com/equinor/fusion-framework/blob/main/packages/cli/docs/auth.md): Local and CI/CD authentication, MSAL, and secure token storage.
+  - - [Migration Guide: v10 to v11](https://github.com/equinor/fusion-framework/blob/main/packages/cli/docs/migration-v10-to-v11.md): Breaking changes, deprecated commands, and upgrade steps.
+  - - [libsecret setup](https://github.com/equinor/fusion-framework/blob/main/packages/cli/docs/libsecret.md): Secure credential storage for Linux users.
+      +- For real-world examples, see the [cookbooks/](https://github.com/equinor/fusion-framework/tree/main/cookbooks) directory.
 
-- Updated dependencies []:
-  - @equinor/fusion-framework-dev-server@1.0.0-next.2
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.2
+  * Key usage notes:
+    - All config and manifest files must use helpers from `@equinor/fusion-framework-cli/app`.
+    - Use `fusion-framework-cli auth login` for local authentication; use `FUSION_TOKEN` for CI/CD.
+    - Deprecated commands (`build-pack`, `build-upload`, etc.) are replaced by `pack`, `upload`, etc. Use `--env` instead of `--service`.
+    - The CLI supports "build once, deploy many" CI/CD workflows.
+    - Utilities like `mergeAppManifests` are available for advanced config/manifest merging.
 
-## 11.0.0-next.3
+  This consolidated changeset replaces all previous CLI-related changesets for this release.
 
 ### Patch Changes
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`eac2234`](https://github.com/equinor/fusion-framework/commit/eac22349aa3ec6d76ed85b6d5a20966a56c32046) Thanks [@odinr](https://github.com/odinr)! - add assetPath to app manifest for non-build commands
-
-- Updated dependencies [[`ba060b7`](https://github.com/equinor/fusion-framework/commit/ba060b7a5fcc4f84891cb416b4d2f7fde231a368)]:
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.2
+- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253) Thanks [@odinr](https://github.com/odinr)! - update Vite to 6.3.5
 
-## 11.0.0-next.2
+- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253) Thanks [@odinr](https://github.com/odinr)! - Upgrade zod dependency to ^3.25.76 in all affected packages.
 
-### Patch Changes
-
-- Updated dependencies [[`84c16d7`](https://github.com/equinor/fusion-framework/commit/84c16d74c3235f809ce4c3e75868be12010ed695)]:
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.1
-  - @equinor/fusion-framework-dev-server@1.0.0-next.1
+- Updated dependencies [[`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253), [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253), [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253), [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253), [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253)]:
+  - @equinor/fusion-framework-dev-portal@1.0.0
+  - @equinor/fusion-framework-dev-server@1.0.0
+  - @equinor/fusion-framework-module-msal-node@1.0.0
+  - @equinor/fusion-imports@1.1.1
 
-## 11.0.0-next.1
+## 10.7.6
 
 ### Patch Changes
 
-- [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`f8a4db1`](https://github.com/equinor/fusion-framework/commit/f8a4db1208ef98eea7f6f286087338ee74858434) Thanks [@odinr](https://github.com/odinr)! - Update `.npmignore` and `package.json` to improve package publishing:
+- [#3268](https://github.com/equinor/fusion-framework/pull/3268) [`7ef5afc`](https://github.com/equinor/fusion-framework/commit/7ef5afc96a8c2cebecedc85703be820d84e3885a) Thanks [@odinr](https://github.com/odinr)! - Fix: Improve type safety and error handling in `AppAssetExportPlugin` (app-assets plugin).
 
-  - Ensure `bin` directory is included in published files by updating `.npmignore` and adding it to the `files` array in `package.json`.
-  - Add `repository` field to `package.json` for better metadata.
+  - Use `unknown as PluginContext` for type casting in `resolveId` and `emitAssetSync` calls.
+  - Add null check and warning if asset emission fails.
+  - Minor code style and safety improvements.
 
-  These changes help ensure all necessary files are included in the published package and improve discoverability and metadata for consumers.
+  This change improves plugin robustness and aligns with best practices for Vite/Rollup plugin development.
 
-## 11.0.0-next.0
-
-### Major Changes
+- [#3268](https://github.com/equinor/fusion-framework/pull/3268) [`7ef5afc`](https://github.com/equinor/fusion-framework/commit/7ef5afc96a8c2cebecedc85703be820d84e3885a) Thanks [@odinr](https://github.com/odinr)! - Upgraded rollup from `4.22.4` to `4.46.3`
 
-- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - The CLI has been rewritten to use Fusion Framework internally to minimize dependencies and improve performance. This change allows the CLI to be more efficient and maintainable. It also means that the CLI is now a first-class citizen in the Fusion Framework ecosystem, providing a more consistent and integrated experience.
-
-  The dev portal has been moved out to a separate package `@equinor/fusion-framework-dev-server`. This separation allows for a more modular architecture, enabling developers to use the dev portal independently of the CLI. It also facilitates easier updates and maintenance of the dev portal without affecting the CLI functionality. It also allows for 3rd party developers to create their own dev portals using the Fusion Framework. Also, moving the dev portal to a separate package allows for better versioning and dependency management, ensuring that developers can always use the latest features and improvements without being tied to the CLI release cycle.
-
-  The dev portal can be configured using the `dev-server.config.js` file, which allows developers to customize the behavior and appearance of the dev portal. This configuration file provides flexibility in how the dev portal operates, enabling developers to tailor it to their specific needs and preferences. **this is currently not documented, but will be in the future**
-
-  Since the dev portal uses the plugin `@equinor/fusion-framework-vite-plugin-spa`, it is possible to specify a live portal to preview the application in the dev portal. This feature allows developers to see their changes in real-time, enhancing the development experience and speeding up the feedback loop. It is particularly useful for testing and debugging applications during development.
-
-  The dev portal also supports mocking API services, which allows developers to simulate backend services without needing a live server. This feature is particularly useful for testing and development, as it enables developers to work on the frontend independently of the backend, ensuring a smoother development process. **this is currently not documented, but will be in the future**
-
-  The dev portal is a key component of the Fusion Framework ecosystem, providing a user-friendly interface for developers to interact with their applications. It allows developers to easily manage and test their applications, providing a streamlined development experience.
-
-  The Dev Portal uses by default the `@equinor/fusion-framework-dev-portal` package, which is the official dev portal package provided by Fusion which is developer-friendly portal for developing and testing Fusion Framework applications. But it is possible to specify any package as a dev portal, allowing for customization of the development experience. This flexibility enables developers to create their own dev portals or use third-party solutions that better fit their needs.
-
-  The CLI now supports the `fusion-framework-cli auth login` command for authentication, which is a more secure and user-friendly way to manage access to Fusion Framework applications. This command simplifies the authentication process, making it easier for developers to log in and start working on their applications without needing to manually set environment variables or manage tokens. _`FUSION_TOKEN`_ is still supported for CI/CD and automation, but the CLI now provides a more streamlined and intuitive way to handle authentication.
-
-  The CLI has now been divided into three main groups:
-
-  - **bin**: This namespace contains executable functions that can be executed from node scripts, handy for automation and scripting or creating a custom CLI.
-  - **commands**: This namespace contains commands that can be executed from the CLI, providing a user-friendly interface for developers to interact with the Fusion Framework.
-  - **lib**: This namespace is reserved for consumers of the CLI, like defining configuration files, exposing interfaces, and other utilities that can be used in custom scripts or applications. This separation allows for better organization and modularity of the CLI codebase, making it easier to maintain and extend.
-
-  **BREAKING CHANGES:**
-
-  the `--service` flag has been removed since the CLI now uses the Fusion Framework internally, which does not require this flag, but uses service discovery to resolve endpoints automatically according to provided Fusion environment variables. This change simplifies the CLI usage and aligns it more closely with the Fusion Framework's architecture, allowing for a more seamless integration and improved developer experience.
-
-  All `app -build-???` has alias to correct commands, but been flagged as deprecated and will be removed in the next major version.
-
-### Minor Changes
-
-- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - Added CLI, bin and lib functionality to the Fusion Framework CLI for portal development and management.
+## 10.7.5
 
 ### Patch Changes
 
-- [#3074](https://github.com/equinor/fusion-framework/pull/3074) [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13) Thanks [@odinr](https://github.com/odinr)! - update Vite to 6.3.5
-
-- Updated dependencies [[`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13), [`6b034e5`](https://github.com/equinor/fusion-framework/commit/6b034e5459094cea0c0f2490335eef3092390a13)]:
-  - @equinor/fusion-framework-dev-server@1.0.0-next.0
-  - @equinor/fusion-framework-dev-portal@1.0.0-next.0
+- [#3164](https://github.com/equinor/fusion-framework/pull/3164) [`31e4477`](https://github.com/equinor/fusion-framework/commit/31e447749cffc6d05e9dc3aef8ec49bd29751714) Thanks [@Noggling](https://github.com/Noggling)! - Fixes a bug where the app module was not using the correct configured HTTP client. Updates the configuration to ensure the app module uses the HTTP client that matches its expected name.
 
 ## 10.7.4
 

package/README.md

@@ -33,8 +33,6 @@ keywords:
   - service discovery
 ---
 
-# Fusion Framework CLI
-
 [![npm version](https://img.shields.io/npm/v/@equinor/fusion-framework-cli.svg?style=flat)](https://www.npmjs.com/package/@equinor/fusion-framework-cli)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](./LICENSE)
 
@@ -42,72 +40,91 @@ keywords:
 
 ## Table of Contents
 
-- [Fusion Framework CLI](#fusion-framework-cli)
-  - [Table of Contents](#table-of-contents)
-  - [Overview](#overview)
-  - [Features \& Benefits](#features--benefits)
-  - [Getting Started](#getting-started)
-    - [1. Install the CLI](#1-install-the-cli)
-    - [2. Initialize or update your app's manifest and config files](#2-initialize-or-update-your-apps-manifest-and-config-files)
-    - [3. Start the development server](#3-start-the-development-server)
-    - [4. Log in to the Fusion Framework (if needed)](#4-log-in-to-the-fusion-framework-if-needed)
-    - [5. Build and publish your app](#5-build-and-publish-your-app)
-    - [6. Upload configuration](#6-upload-configuration)
-  - [Common Commands](#common-commands)
-  - [Example: package.json](#example-packagejson)
-  - [Troubleshooting](#troubleshooting)
-  - [Documentation](#documentation)
-  - [Contributing](#contributing)
-  - [Tooling Roadmap](#tooling-roadmap)
+- [Table of Contents](#table-of-contents)
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Features \& Benefits](#features--benefits)
+- [Getting Started](#getting-started)
+- [Common Commands](#common-commands)
+- [Example: package.json](#example-packagejson)
+- [Documentation](#documentation)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+  - [Getting Help](#getting-help)
 
 ## Overview
 
 Fusion Framework CLI is a command-line tool for developing, building, and publishing applications and portal templates within the Fusion Framework ecosystem. It streamlines workflows, automates common tasks, and supports modern CI/CD pipelines.
 
+**What you can build:**
+- **Fusion Applications**: Interactive web apps that run within the Fusion Portal
+- **Portal Templates**: Customizable portal configurations for different business contexts
+
+**Key capabilities:**
+- Development server with hot reload and service discovery
+- Application manifest and configuration management
+- Automated building, bundling, and deployment
+- Environment-specific configuration handling
+- Integrated authentication and authorization
+- CI/CD pipeline support with automated publishing
+
+## Prerequisites
+
+- **Node.js** (LTS version recommended)
+- **pnpm** (or npm/yarn) package manager
+- **Fusion Framework app or portal project** (or create a new one)
+- **Access to Fusion services** (for authentication and deployment)
+
 ## Features & Benefits
 
-- **Unified developer experience**: One tool for development, build, and deployment.
-- **Rapid local development**: Hot reload and fast feedback.
-- **Environment-specific configuration**: Manage manifests and configs per environment.
-- **Integrated authentication**: Secure your apps locally and in CI/CD pipelines.
-- **Service discovery**: Built-in support for Fusion services.
-- **Extensible architecture**: Widgets, portals, and more coming soon.
-- **Comprehensive documentation**: Migration guides, app/portal setup, and troubleshooting.
+- **🚀 Unified developer experience**: Single tool for the entire development lifecycle - from local development to production deployment
+- **⚡ Rapid local development**: Built-in dev server with hot reload, service discovery, and real-time feedback
+- **🎯 Environment-specific configuration**: Seamlessly manage manifests and configs across dev, test, and production environments
+- **🔐 Integrated authentication**: Secure your apps locally and in CI/CD with Azure AD integration and token management
+- **🔍 Service discovery**: Built-in support for Fusion services with automatic endpoint resolution
+- **📦 Automated bundling & deployment**: One-command building, packaging, and publishing to Fusion registry
+- **🏗️ Extensible architecture**: Support for apps, portals, widgets, and future Fusion components
+- **📚 Comprehensive documentation**: Migration guides, detailed setup instructions, and troubleshooting resources
 
 ## Getting Started
 
-### 1. Install the CLI
+**Install the CLI**
 
 ```sh
 pnpm add -D @equinor/fusion-framework-cli
 ```
 
-### 2. Initialize or update your app's manifest and config files
+**Initialize or update your app's manifest and config files**
 
-See [Developing Apps](./docs/application.md) for manual setup and configuration guidance.
+Create the required configuration files for your app:
 
-### 3. Start the development server
+- `app.manifest.ts` - Defines your app's metadata and capabilities
+- `app.config.ts` - Contains runtime configuration and environment variables
+
+See [Developing Apps](./docs/application.md) for detailed setup and configuration guidance.
+
+**Start the development server**
 
 ```sh
 pnpm fusion-framework-cli dev
 ```
 
-### 4. Log in to the Fusion Framework (if needed)
+**Log in to the Fusion Framework (if needed)**
 
 ```sh
 pnpm fusion-framework-cli auth login
 ```
 
-### 5. Build and publish your app
+**Build and publish your app**
 
 ```sh
 pnpm fusion-framework-cli publish --env <environment>
 ```
 
-### 6. Upload configuration
+**Upload configuration**
 
 ```sh
-pnpm fusion-framework-cli app config --upload --env <environment>
+pnpm fusion-framework-cli app config --publish --env <environment>
 ```
 
 > **Tip:** For CI/CD and automation, set the `FUSION_TOKEN` environment variable. See [Authentication](./docs/auth.md) for details.
@@ -116,8 +133,7 @@ pnpm fusion-framework-cli app config --upload --env <environment>
 
 | Command                                | Description                          |
 | -------------------------------------- | ------------------------------------ |
-| `pnpm fusion-framework-cli dev`        | Start local development server       |
-| `pnpm fusion-framework-cli auth login` | Authenticate with Fusion             |
+| `pnpm fusion-framework-cli auth ...` | Authenticate with Fusion             |
 | `pnpm fusion-framework-cli app ...`    | Working with Fusion applications     |
 | `pnpm fusion-framework-cli portal ...` | Working with Fusion portal templates |
 
@@ -128,42 +144,81 @@ A minimal example for a Fusion Framework app:
 ```json
 {
   "name": "@equinor/fusion-framework-app",
-  "version": "0.0.0",
-  "description": "Fusion Framework App",
-  "main": "dist/index.js",
+  "version": "1.0.0",
+  "description": "My Fusion Framework Application",
+  "main": "dist/bundle.js",
   "files": [
-    "path-to-some-file/foo.png"
-  ]
+    "dist/",
+    "assets/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "fusion-framework-cli app build",
+    "dev": "fusion-framework-cli dev",
+    "publish": "fusion-framework-cli app publish"
+  },
+  "devDependencies": {
+    "@equinor/fusion-framework-cli": "^11.0.0"
+  }
 }
 ```
 
-> **Note:** The `main` field should point to the build output (e.g., `dist/index.js`).
+**Key fields:**
+- `main`: **Required** - Points to your build output directory (CLI uses this to determine where to place built files)
+- `files`: Specifies which files to include in your app bundle
+- `scripts`: Convenient shortcuts for common CLI commands
+
+> **Note:** The CLI determines the build output location from the `main` field in your package.json. If not specified, it defaults to `dist/bundle.js`.
+
+## Documentation
+
+**Getting Started**
+- [Developing Apps](./docs/application.md): Complete guide to building, configuring, and deploying Fusion applications
+- [Developing Portals](./docs/portal.md): Guide to building, configuring, and publishing portal templates
+
+**Setup & Configuration**
+- [Authentication](./docs/auth.md): Setting up authentication for local development and CI/CD environments
+- [libsecret Installation](./docs/libsecret.md): Fix credential storage issues on Linux systems
+
+**Migration & Updates**
+- [Migration Guide: v10 to v11](./docs/migration-v10-to-v11.md): Breaking changes, deprecated commands, and upgrade instructions
+
+**Additional Resources**
+- [CLI Command Reference](./docs/application.md#commands): Detailed documentation of all available commands and options
+- [CI/CD Best Practices](./docs/application.md#cicd): Automated workflows and deployment strategies
+- [Troubleshooting Guide](./docs/application.md#troubleshooting--faq): Common issues and solutions
+
+> **Need more help?** Check the [docs folder](./docs/) for additional guides and examples.
 
 ## Troubleshooting
 
-If you encounter errors like `libsecret-1.so.0: cannot open shared object file`, it means `libsecret` is missing. see the [libsecret installation guide](./docs/libsecret.md) for instructions on how to install it based on your operating system.
+### Common Issues
 
-- **Command not found?** Ensure your `node_modules/.bin` is in your PATH or use `pnpm`/`npx`.
-- **Authentication issues?** See [Authentication](./docs/auth.md) for troubleshooting tokens and login.
-- **Build errors?** Check your app's manifest and config files for typos or missing fields.
-- **Need help?** Open an issue or see the [docs folder](./docs/).
+**Authentication & Credentials**
+- **Authentication issues?** See [Authentication Guide](./docs/auth.md) for token setup and troubleshooting
+- **libsecret errors on Linux?** Install libsecret using our [installation guide](./docs/libsecret.md)
 
-## Documentation
+**CLI & Commands**
+- **Command not found?** Ensure `node_modules/.bin` is in your PATH or use `pnpm`/`npx`
+- **Permission errors?** Check that you have the correct access rights to Fusion services
 
-- [Migration Guide: v10 to v11](./docs/migration-v10-to-v11.md): Learn about breaking changes and how to upgrade.
-- [Developing Apps](./docs/application.md): Step-by-step guide to building and configuring apps.
-- [Developing Portals](./docs/portal.md): Guide to building, configuring, and publishing portal templates.
-- [Authentication](./docs/auth.md): Setting up authentication for local and CI/CD environments.
-- For more guides and advanced topics, see the [docs folder](./docs/).
+**Build & Development**
+- **Build errors?** Verify your `app.manifest.ts` and `app.config.ts` files for syntax errors
+- **Dev server not starting?** Check for port conflicts (default: 3000) or use `--port` option
+- **Missing dependencies?** Ensure all required packages are installed with `pnpm install`
 
-## Contributing
+**Publishing & Deployment**
+- **Upload failures?** Verify your app is registered in the Fusion App Admin
+- **Environment issues?** Check that you're using the correct `--env` parameter
 
-We welcome contributions! See our [contributing guide](../../contributing/development.md) for details on how to get started, coding standards, and submitting pull requests.
+### Getting Help
 
-## Tooling Roadmap
+- **Detailed troubleshooting:** See our [comprehensive troubleshooting guide](./docs/application.md#troubleshooting--faq)
+- **Found a bug?** Open an issue on our GitHub repository
+- **Need support?** Check the [docs folder](./docs/) or reach out to the Fusion team
 
-- **Vitest integration** (coming soon)
 ---
 
 For more information, visit the [docs folder](./docs/) or open an issue for support.
 
+