Fusion Help Docs

Fusion Help Documentation

Author, structure, and publish help docs (articles, release notes, FAQs) via fhelp CLI.

When to use

• Write help article for Fusion app
• Create/update release notes
• Set up docs folder structure + config
• Structure markdown for help system
• Publish/sync docs to Fusion environment
• Add FAQ entries
• Set up CI/CD pipeline to auto-publish

When not to use

• Modifying fusion-help-cli source (tooling/fusion-help-cli/)
• Changing Fusion.Services.Help backend API
• General markdown editing unrelated to Fusion Help
• Non-documentation tasks

Required inputs

Collect before creating:

Unknown app key → check app admin:

• CI: https://fusion.ci.fusion-dev.net/apps/app-admin
• Production: https://fusion.equinor.com/apps/app-admin

Look in "Admins" section — must be listed as admin to publish.

Instructions

1. Set up docs folder structure

Create folder layout:

docs/
  help/
    articles/                    # Markdown article files
      images/                    # Article images (PNG format)
    release-notes/               # Markdown release note files
      images/                    # Release note images (PNG format)
    faqs/                        # Optional: markdown FAQ body overrides
    help-articles.json           # Article config
    help-release-notes.json      # Release notes config (if using release notes)

Folder and config names are flexible — must match what you pass to fhelp.

2. Create the article config file

Create help-articles.json (tells CLI which articles to sync):

{
  "articles": [
    {
      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)
      "title": "Getting Started",               // Display title in Fusion Help
      "appKey": "my-app",                       // Your Fusion app key
      "sortOrder": 1.0,                         // Controls display order (lower = first)
      "summary": "Learn how to get started.",   // Short description shown in article list
      "tags": ["getting-started", "onboarding"],// Searchable tags
      "relevantApps": []                        // Optional: other app keys where this shows
    }
  ]
}

Config field reference

3. Write article content

Create markdown files in the articles root folder. The filename (without .md) must match the slug in the config.

Article writing guidelines:

• Write for end-users of the Fusion app
• Use ##, ### for structure — avoid # (title comes from config)
• Place images in images/; reference with ![Alt text](images/my-screenshot.png)
• CLI auto-uploads images + rewrites paths to CDN
• Images must be PNG (CLI limitation)
• One topic per article
• Link related articles by title (platform handles deep linking)

Example article (docs/help/articles/my-app-getting-started.md):

## Overview

This guide walks you through the basics of using My App.

## Prerequisites

Before you begin, make sure you have:
- Access to the Fusion portal
- The correct role assigned to your user

## Step 1: Navigate to the app

Open Fusion and search for "My App" in the app launcher.

![App launcher](images/app-launcher.png)

## Step 2: Create your first item

Click the **New** button in the toolbar to create your first item.

## Need help?

Contact the team on Teams or check the FAQ section.

4. Create the release notes config file (optional)

Create help-release-notes.json if team publishes release notes:

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              // Must match the .md filename
      "title": "Version 2.0 Release",           // Display title
      "appKey": "my-app",                       // Your Fusion app key
      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)
      "tags": ["release", "v2"],                // Searchable tags
      "relevantApps": []                        // Optional: other app keys
    }
  ]
}

Release notes config field reference

Example release note (docs/help/release-notes/my-app-v2-release.md):

## What's new in Version 2.0

### New dashboard

We've completely redesigned the dashboard with new charts and filtering capabilities.

![New dashboard](images/new-dashboard.png)

### Performance improvements

- Page load times reduced by 40%
- Search results now appear in under 1 second

### Bug fixes

- Fixed an issue where filters would reset on navigation
- Corrected date formatting in the export feature

5. Install and authenticate the CLI

Install from the Fusion Public feed:

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Update an existing installation:

dotnet tool uninstall --global Fusion.Help.Cli
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Authenticate via Azure CLI:

az login

CLI uses DefaultAzureCredentials — picks up az login session automatically.

6. Publish documentation

Sync articles:

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

Sync release notes:

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

Command flags:

Environment promotion order: ci → fqa → fprd (skip tr unless testing infrastructure).

Test in ci before promoting to fqa then fprd.

7. Set up CI/CD pipeline (recommended)

Automate publishing via Azure DevOps or GitHub Actions.

Azure DevOps pipeline example:

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli
    displayName: "Install fusion help CLI"

  - task: AzureCLI@2
    displayName: "Sync help articles"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "Sync release notes"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions example:

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          dotnet tool install --global \
            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
            Fusion.Help.Cli

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

8. FAQs (supplementary)

FAQs use an Excel-based workflow and require app-level access. This is a temporary solution best suited for scenarios where FAQs span multiple apps.

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

For most teams, managing FAQs through the Fusion Help Admin UI at https://fusion.equinor.com/apps/fusion-help-admin is simpler.

Expected output

• docs/help/ folder with articles, images, and config
• Markdown article file(s) with proper content
• Valid help-articles.json (+ optional help-release-notes.json)
• How to install, auth, and run fhelp
• CI/CD pipeline snippet (optional)

Troubleshooting

Safety & constraints

• Never use `--no-validation` without understanding — can overwrite UI-created content
• Test in ci before publishing to fprd
• sourceSystem auto-set to Fusion.Help.Cli; CLI and UI articles have different source systems and won't conflict unless --no-validation is used
• Slugs must be globally unique — use app-specific prefix (e.g. my-app-getting-started)
• Never commit access tokens — use az login or pipeline service principals

Overview

{{Brief description of what the app does and who it's for.}}

Prerequisites

Before you begin, make sure you have:

• Access to the Fusion portal
• {{Any role or permission requirements}}

Step 1: Open the app

Navigate to Fusion and search for "{{App Name}}" in the app launcher, or open it directly via the sidebar.

Step 2: {{First key action}}

{{Describe the first thing a new user should do.}}

Step 3: {{Second key action}}

{{Describe the next step.}}

Tips

• {{Helpful tip for new users}}
• {{Another tip}}

Need help?

Check the FAQ section or contact the team on {{Teams channel / email}}.

What's new in {{Version}}

{{Feature 1 heading}}

{{Description of the feature. Include screenshots where helpful.}}

{{Feature 2 heading}}

{{Description.}}

Improvements

• {{Improvement 1}}
• {{Improvement 2}}

Bug fixes

• {{Fix 1}}
• {{Fix 2}}

Known issues

• {{Known issue, if any}}

Changelog

0.0.2 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md and references.

• Drop articles, filler, hedging from SKILL.md activation body
• Compress cli-reference reference

0.0.1 - 2026-03-17

patch

• #83 `f776146` - Add fusion-help-docs skill

• Guides app teams through authoring and publishing help documentation using fusion-help-cli
• Covers articles, release notes, and FAQs

fusion-help-cli Reference

Installation

# Install from Fusion Public feed
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

# Update (uninstall + reinstall)
dotnet tool uninstall --global Fusion.Help.Cli
dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli

Authentication

Uses DefaultAzureCredential. Simplest method:

az login

CI/CD: use service principal:

az login --service-principal -u <app-id> -p <client-secret> --tenant 3aa4a235-b6e2-48d5-9195-7fcf05b459b0

Or pass JWT token via --token flag.

Commands

fhelp article sync

Syncs article markdown files to the Fusion Help API.

fhelp article sync -f <config-file> -r <articles-root> -e <environment> [-t <token>] [--no-validation] [-v]

Behavior: 1. Reads the config JSON and iterates each article entry 2. Looks for {root}/{slug}.md — skips if file not found 3. Scans markdown for image references, uploads any local images to the Help assets API 4. Rewrites image paths to the Fusion CDN (/help-proxy/assets/resources/images/{slug}/processed.webp) 5. Checks if the article already exists on the server (by slug) 6. Creates (POST) if new, patches (PATCH) if changed, skips if unchanged 7. Validates sourceSystem matches — refuses to overwrite UI-created articles unless --no-validation is set

fhelp releasenotes sync

Syncs release note markdown files to the Fusion Help API.

fhelp releasenotes sync -f <config-file> -r <release-notes-root> -e <environment> [-t <token>] [--no-validation] [-v]

Same flags/behavior as article sync; uses releaseNotes array, includes publishedDate.

fhelp faq sync

Syncs FAQs from Excel. Temporary solution for multi-app FAQs.

fhelp faq sync -f <excel-file> -e <environment> [-r <faq-root>] [-p <slug-prefix>] [-t <token>] [--no-validation] [-v]

Note: FAQ sync requires APP ACCESS via internal API functions — not available to all users.

Environments

Promotion order: ci → fqa → fprd

Source system

The CLI stamps all content with sourceSystem: "Fusion.Help.Cli". Content created via Fusion Help Admin UI has source fusion-help-admin. CLI will not overwrite content from a different source system unless --no-validation is used.

Image handling

• Images must be PNG format
• Place images in an images/ subfolder under the article/release-notes root
• Reference them in markdown with standard syntax: ![Alt text](images/screenshot.png)
• The CLI hashes each image and creates a unique slug (img-{article-slug}-{hash})
• Images are only uploaded if they don't already exist (based on the hash slug)
• After upload, markdown paths are rewritten to /help-proxy/assets/resources/images/{slug}/processed.webp

Slug naming conventions

Slugs must be globally unique across all apps. Pattern:

{app-prefix}-{topic}

Examples:

• fra-getting-started
• my-app-new-features
• my-app-v2-release