fusion-help-docs

What this skill does

# 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:

| Input | Required | Description |
|-------|----------|-------------|
| **App key** | Yes | The Fusion app key (e.g. `my-app`, `resource-allocation-landingpage`). User must be admin for this app. |
| **Content type** | Yes | `articles`, `release-notes`, or `faqs` |
| **Docs root path** | Yes | Where the team stores their docs (e.g. `docs/help/`) |
| **Target environment** | For publish | `ci`, `fqa`, `tr`, or `fprd` |

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):

```jsonc
{
  "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

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `slug` | Yes | string | Unique identifier. Must match a `{slug}.md` file in the articles root folder. Use kebab-case. |
| `title` | Yes | string | Human-readable title displayed in Fusion Help. |
| `appKey` | Yes | string | Fusion app key this article belongs to. You must be admin for this app. |
| `sortOrder` | No | number | Controls display order. Lower numbers appear first. Default varies. Use decimals (1.0, 1.1, 2.0) for flexible ordering. |
| `summary` | Yes | string | Short description shown in article listings. |
| `tags` | No | string[] | Searchable tags for categorization. |
| `relevantApps` | No | string[] | Additional app keys where this article should appear. |

### 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`):

```markdown
## 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:

```jsonc
{
  "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

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `slug` | Yes | string | Unique identifier. Must match a `{slug}.md` file in the release notes root folder. |
| `title` | Yes | string | Release note title. |
| `appKey` | Yes | string | Fusion app key. You must be admin. |
| `publishedDate` | Yes | ISO 8601 date | When the release was published. |
| `tags` | No | string[] | Searchable tags. |
| `relevantApps` | No | string[] | Additional app keys. |

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

```markdown
## 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:**

```powershell
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:**

```powershell
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:**

```powershell
az login
```

CLI uses `DefaultAzureCredentials` — picks up `az login` session automatically.

### 6. Publish documentation

**Sync articles:**

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

**Sync release notes:**

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

**Command flags:**

| Flag | Description |
|------|-------------|
| `-f`, `--file` | Path to the JSON config file |
| `-r`, `--root` | Path to the folder containing markdown files |
| `-e`, `--env` | Target environment: `ci`, `fqa`, `tr`, `fprd` |
| `-t`, `--token` | Override the access token (optional) |
| `-v`, `--verbose` | Show detailed logging output |
| `--no-validation` | Skip source system check — **use with caution**, can overwrite UI-created content |

**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:**

``