feat: restructure user guide following Diataxis information architecture

# What to read next

[latest-hackfest]: https://osm.etsi.org/wikipub/index.php/Latest_OSM_Hackfest_Material#Hackfest_Material

[developer-guide]: https://osm.etsi.org/docs/developer-guide/

If you want to learn more, these additional contents are highly recommended:

- **[VNF Onboarding Guide](https://osm.etsi.org/docs/vnf-onboarding-guidelines).** This guide includes all that you might need to onboard your VNF or applications in OSM.

- **[OSM Developer Guide][developer-guide].** If you want to contribute to OSM development, it is highly recommended reading this guide first.

- **[Sample VNF Packages](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages.git).**

- **[Contents from latest edition of OSM Hackfest][latest-hackfest].**

- [OSM Workshops and Webinars](https://osm.etsi.org/wikipub/index.php/OSM_workshops_and_events)

- [Release notes and white papers](https://osm.etsi.org/wikipub/index.php/Release_notes_and_whitepapers)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Purpose

This is the **OSM User Guide**, a Sphinx-based documentation site published at https://osm.etsi.org/docs/user-guide/. It covers installation, usage, architecture, VIM setup, cluster management, CLI reference, and troubleshooting for all active OSM releases.

## Build Commands

```bash

# Build versioned HTML (output: _build/html/)

tox -e build

# Live preview with auto-rebuild on port 8001

tox -e run

# Publish to ETSI FTP (requires credentials in local/.credentials)

tox -e publish

# Publish to the test location on ETSI FTP

tox -e test-publish

```

`tox -e build` runs `sphinx-multiversion`, which generates a separate HTML subtree for every release branch (`v10`–`v19`) plus `develop` and `latest`. It also runs `fix_cross_references.sh` afterwards to patch Sphinx's incorrect `.md` → `.html` link conversion.

For `tox -e publish`, credentials must be stored in `local/.credentials` with `USERNAME=` and `PASSWORD=` lines. That file is gitignored.

## Repository Structure

The guide follows the **Diataxis** information architecture, organised into topic folders. Each folder has its own `index.rst` for the Sphinx toctree hierarchy.

```

osm-user-guide/

├── index.rst                  # Sphinx master toctree (hierarchical, folder-based)

├── index.md                   # Navigation reference (excluded from Sphinx)

├── navigation.md              # Quick-nav links (excluded from Sphinx)

├── conf.py                    # Sphinx configuration

├── Makefile

├── tox.ini                    # Build environments: build, run, publish, test-publish

├── requirements.txt           # Sphinx + plugins pinned versions

├── _static/                   # CSS and images

├── _templates/                # Jinja2 templates (layout, topbar, versions)

├── assets/                    # Diagram images (PNG, JPG)

├── fix_cross_references.sh    # Post-build: fixes .md → .html links

├── updater.sh                 # Bulk version number updates across all files

├── upload_doc.sh              # FTP upload helper used by tox publish

├── .gitlab-ci.yml             # CI: builds on every push, publishes on protected branches

│

├── getting-started/

│   ├── index.rst

│   └── quickstart.md

│

├── tutorial/

│   ├── index.rst

│   ├── charmed-osm-cnf.md

│   └── k8s-declarative-framework.md

│

├── explanation/

│   ├── index.rst

│   ├── architecture.md

│   └── service-assurance.md

│

├── how-to/

│   ├── index.rst

│   ├── installing-osm.md

│   ├── managing-vim-accounts.md

│   ├── managing-k8s-clusters.md

│   ├── managing-profiles.md

│   ├── managing-oka.md

│   ├── managing-ksu.md

│   ├── managing-app-instances.md

│   ├── managing-users-projects-roles.md

│   ├── troubleshooting.md

│   ├── upgrading-osm.md

│   ├── running-tests.md

│   ├── openvim-installation.md

│   ├── k8s-installation.md

│   ├── lxd-cluster.md

│   ├── tacacs-authentication.md

│   ├── preparing-git-repos-flux.md

│   └── nfv/

│       ├── index.rst

│       ├── managing-vnf-ns-packages.md

│       ├── deploying-network-services.md

│       ├── operating-network-services.md

│       ├── scaling-network-services.md

│       ├── healing-network-services.md

│       ├── monitoring-network-services.md

│       ├── network-slices.md

│       └── sdn-wim.md

│

├── reference/

│   ├── index.rst

│   ├── client-commands.md

│   ├── information-model.md

│   ├── nbi-api.md

│   ├── releases.md

│   ├── architecture-ref.md

│   ├── declarative-framework.md

│   ├── packages.md

│   └── naming-conventions.md

│

├── developer-guide/

│   ├── index.rst

│   ├── 01-workflow-osm-tools.md

│   ├── 02-developer-how-to.md

│   ├── 03-developer-how-to-for-modules.md

│   ├── 04-merge-conflicts.md

│   ├── 05-git-review.md

│   └── 06-testing-before-committing.md

│

└── others/

    ├── index.rst

    ├── faq.md

    └── contributing-to-docs.md

```

## Source Format

All content is written in **Markdown** (`.md`). Each folder also has an `index.rst` (RST format) to provide Sphinx toctree entries for that section. Both formats are supported via `recommonmark`.

## Image Paths

Images live in `assets/` at the repo root. Use relative paths from the document's location:

- Files in top-level folders (e.g. `how-to/`): `../assets/image.png`

- Files two levels deep (e.g. `how-to/nfv/`): `../../assets/image.png`

## Versioning

The guide is versioned per OSM release branch. `sphinx-multiversion` builds all branches matching the patterns in `conf.py`:

```python

smv_branch_whitelist = r'(v19|v18|v17|...|v10)'

smv_tag_whitelist    = r'(latest|develop)'

```

Each version is published under `/versions/<branch>/` on the ETSI site. When working on documentation for a specific release, check out the corresponding branch (e.g. `v19`).

To update version numbers across all files when preparing a new release, use:

```bash

./updater.sh <old_version> <new_version>

```

## CI/CD

`.gitlab-ci.yml` runs two stages:

1. **build-docs** — runs `tox -e build` on every push; HTML output is saved as a CI artifact

2. **deploy-job** — runs only on protected branches; uses `FTP_USERNAME` and `FTP_PASSWORD` CI variables to publish to the ETSI FTP server

## Key Dependencies

- `Sphinx 5.1.1` — documentation builder

- `sphinx-rtd-theme 1.0.0` — Read the Docs theme

- `recommonmark 0.7.1` — Markdown support in Sphinx

- `sphinx-multiversion 0.2.4` — multi-branch versioned builds

- `sphinx-autobuild` — live preview server (used by `tox -e run`)

    </div>

    <div class="topbar-right">

        <a href="https://osm.etsi.org/docs/user-guide/latest/">Docs</a>

        <a href="https://osm.etsi.org/docs/user-guide/latest/03-installing-osm.html">Install</a>

        <a href="https://osm.etsi.org/docs/user-guide/latest/how-to/installing-osm.html">Install</a>

        <a href="https://osm.etsi.org/news-events/news">News & Events</a>

        <div class="dropdown">

            <button>Community</button>