FirelyTeam · ArdonToonstra · Jun 17, 2026 · Jun 18, 2026 · Jun 18, 2026 · Jun 18, 2026
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.7"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

diff --git a/Dependencies.rst b/Dependencies.rst
@@ -4,7 +4,7 @@ Dependencies of Simplifier and their licenses
 =============================================
 
 Simplifier is built using libraries from Microsoft and the Firely .NET SDK, along with a list of other libraries.
-This is the full list of direct depencies that Simplifier has on other libraries, along with their licenses.
+This is the full list of direct dependencies that Simplifier has on other libraries, along with their licenses.
 
 .. include:: generated/dependencies.rstinc
 
diff --git a/FAQs.rst b/FAQs.rst
@@ -12,13 +12,13 @@ Once a package is created the FHIR community should be able to depend on the con
 Can I customize the way resources are shown in Simplifier?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is possible by using `Metadata Expressions <./getting_started/simplifierResources.html#metadata-expressions>`_. Note that in order to use Metadata Expressions, you need at least a `Professional plan <https://simplifier.net/pricing>`_.
+This is possible by using `Metadata Expressions <./adding_content/metadata-expressions.html>`_. Note that in order to use Metadata Expressions, you need at least a `Professional plan <https://simplifier.net/pricing>`_.
 
 Can I sync from Simplifier back to GitHub using Simplifier GitHub Sync?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-It is only possible to sync from GitHub to Simplifier and not the other way round. A workaround would be to sync your Simplifier work with your local folder using Forge or Firely Terminal and then commit that to Github. 
-For more information, have a look at our `GitHub Sync documentation <./data_governance_and_quality_control/simplifierGithub.html>`_.
+It is only possible to sync from GitHub to Simplifier and not the other way round. A workaround would be to sync your Simplifier work with your local folder using Forge or Firely Terminal and then commit that to GitHub. 
+For more information, have a look at our `GitHub Sync documentation <./adding_content/github.html>`_.
 
 Does Simplifier support Custom Resources?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/accessibility.rst b/accessibility.rst
@@ -27,7 +27,7 @@ General notes
   our users in creating accessible content, the flexibility of the platform requires users to
   check their own generated content for accessibility.
 
-* The tree rendering of FHIR resources can be navigated by keyboard when Javascript is enabled:
+* The tree rendering of FHIR resources can be navigated by keyboard when JavaScript is enabled:
 
   - Tab until the full tree is selected.
   - Then navigate the three rows with the up and down arrows. When using a screen reader this
@@ -354,7 +354,7 @@ Table 1: Success Criteria, Level A
     - Known issues:
 
        * [SIM-1371] Drag and drop for page reordering in IG editor has no keyboard/button alternative
-       * [SIM-1387] Unable to succesfully navigate account avatar with keyboard only
+       * [SIM-1387] Unable to successfully navigate account avatar with keyboard only
 
   * - `2.5.2 Pointer Cancellation`_
 
@@ -618,69 +618,69 @@ Table 2: Success Criteria, Level AA
     - Supports
     - There where status is conveyed by graphical elements, like a progress bar, the status is programmatically available to the user agent.
 
-.. _Web Content Accessibility Guidelines 2.0: http://www.w3.org/TR/2008/REC-WCAG20-20081211
+.. _Web Content Accessibility Guidelines 2.0: https://www.w3.org/TR/2008/REC-WCAG20-20081211/
 .. _Web Content Accessibility Guidelines 2.1: https://www.w3.org/TR/WCAG21
 .. _Web Content Accessibility Guidelines 2.2: https://www.w3.org/TR/WCAG22
 .. _WCAG 2.2 Conformance Requirements: https://www.w3.org/TR/WCAG22/#conformance-to-wcag-2-2
 
 .. _WAVE Web Accessibility Evaluation Tool: https://wave.webaim.org/
 .. _Microsoft Narrator: https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1
 
-.. _1.1.1 Non-text Content: http://www.w3.org/TR/WCAG20/#text-equiv-all
-.. _1.2.1 Audio-only and Video-only: http://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt
-.. _1.2.2 Captions: http://www.w3.org/TR/WCAG20/#media-equiv-captions
-.. _1.2.3 Audio Description or Media Alternative: http://www.w3.org/TR/WCAG20/#media-equiv-audio-desc
-.. _1.3.1 Info and Relationships: http://www.w3.org/TR/WCAG20/#content-structure-separation-programmatic
-.. _1.3.2 Meaningful Sequence: http://www.w3.org/TR/WCAG20/#content-structure-separation-sequence
-.. _1.3.3 Sensory Characteristics: http://www.w3.org/TR/WCAG20/#content-structure-separation-understanding
-.. _1.4.1 Use of Color: http://www.w3.org/TR/WCAG20/#visual-audio-contrast-without-color
-.. _1.4.2 Audio Control: http://www.w3.org/TR/WCAG20/#visual-audio-contrast-dis-audio
-.. _2.1.1 Keyboard: http://www.w3.org/TR/WCAG20/#keyboard-operation-keyboard-operable
-.. _2.1.2 No Keyboard Trap: http://www.w3.org/TR/WCAG20/#keyboard-operation-trapping
+.. _1.1.1 Non-text Content: https://www.w3.org/TR/WCAG20/#text-equiv-all
+.. _1.2.1 Audio-only and Video-only: https://www.w3.org/TR/WCAG20/#media-equiv-av-only-alt
+.. _1.2.2 Captions: https://www.w3.org/TR/WCAG20/#media-equiv-captions
+.. _1.2.3 Audio Description or Media Alternative: https://www.w3.org/TR/WCAG20/#media-equiv-audio-desc
+.. _1.3.1 Info and Relationships: https://www.w3.org/TR/WCAG20/#content-structure-separation-programmatic
+.. _1.3.2 Meaningful Sequence: https://www.w3.org/TR/WCAG20/#content-structure-separation-sequence
+.. _1.3.3 Sensory Characteristics: https://www.w3.org/TR/WCAG20/#content-structure-separation-understanding
+.. _1.4.1 Use of Color: https://www.w3.org/TR/WCAG20/#visual-audio-contrast-without-color
+.. _1.4.2 Audio Control: https://www.w3.org/TR/WCAG20/#visual-audio-contrast-dis-audio
+.. _2.1.1 Keyboard: https://www.w3.org/TR/WCAG20/#keyboard-operation-keyboard-operable
+.. _2.1.2 No Keyboard Trap: https://www.w3.org/TR/WCAG20/#keyboard-operation-trapping
 .. _2.1.4 Character Key Shortcuts: https://www.w3.org/TR/WCAG21/#character-key-shortcuts
-.. _2.2.1 Timing Adjustable: http://www.w3.org/TR/WCAG20/#time-limits-required-behaviors
-.. _2.2.2 Pause, Stop, Hide: http://www.w3.org/TR/WCAG20/#time-limits-pause
-.. _2.3.1 Three Flashes or Below Threshold: http://www.w3.org/TR/WCAG20/#seizure-does-not-violate
-.. _2.4.1 Bypass Blocks: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-skip
-.. _2.4.2 Page Titled: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-title
-.. _2.4.3 Focus Order: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-focus-order
-.. _2.4.4 Link Purpose (In Context): http://www.w3.org/TR/WCAG20/#navigation-mechanisms-refs
+.. _2.2.1 Timing Adjustable: https://www.w3.org/TR/WCAG20/#time-limits-required-behaviors
+.. _2.2.2 Pause, Stop, Hide: https://www.w3.org/TR/WCAG20/#time-limits-pause
+.. _2.3.1 Three Flashes or Below Threshold: https://www.w3.org/TR/WCAG20/#seizure-does-not-violate
+.. _2.4.1 Bypass Blocks: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-skip
+.. _2.4.2 Page Titled: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-title
+.. _2.4.3 Focus Order: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-focus-order
+.. _2.4.4 Link Purpose (In Context): https://www.w3.org/TR/WCAG20/#navigation-mechanisms-refs
 .. _2.5.1 Pointer Gestures: https://www.w3.org/TR/WCAG21/#pointer-gestures
 .. _2.5.2 Pointer Cancellation: https://www.w3.org/TR/WCAG21/#pointer-cancellation
 .. _2.5.3 Label in Name: https://www.w3.org/TR/WCAG21/#label-in-name
 .. _2.5.4 Motion Actuation: https://www.w3.org/TR/WCAG21/#motion-actuation
-.. _3.1.1 Language of Page: http://www.w3.org/TR/WCAG20/#meaning-doc-lang-id
-.. _3.2.1 On Focus: http://www.w3.org/TR/WCAG20/#consistent-behavior-receive-focus
-.. _3.2.2 On Input: http://www.w3.org/TR/WCAG20/#consistent-behavior-unpredictable-change
+.. _3.1.1 Language of Page: https://www.w3.org/TR/WCAG20/#meaning-doc-lang-id
+.. _3.2.1 On Focus: https://www.w3.org/TR/WCAG20/#consistent-behavior-receive-focus
+.. _3.2.2 On Input: https://www.w3.org/TR/WCAG20/#consistent-behavior-unpredictable-change
 .. _3.2.6 Consistent Help: https://www.w3.org/TR/WCAG22/#consistent-help
 .. _3.3.7 Redundant Entry: https://www.w3.org/TR/WCAG22/#redundant-entry
-.. _3.3.1 Error Identification: http://www.w3.org/TR/WCAG20/#minimize-error-identified
-.. _3.3.2 Labels or Instructions: http://www.w3.org/TR/WCAG20/#minimize-error-cues
-.. _4.1.1 Parsing: http://www.w3.org/TR/WCAG20/#ensure-compat-parses
-.. _4.1.2 Name, Role, Value: http://www.w3.org/TR/WCAG20/#ensure-compat-rsv
+.. _3.3.1 Error Identification: https://www.w3.org/TR/WCAG20/#minimize-error-identified
+.. _3.3.2 Labels or Instructions: https://www.w3.org/TR/WCAG20/#minimize-error-cues
+.. _4.1.1 Parsing: https://www.w3.org/TR/WCAG20/#ensure-compat-parses
+.. _4.1.2 Name, Role, Value: https://www.w3.org/TR/WCAG20/#ensure-compat-rsv
 
-.. _1.2.4 Captions (Live): http://www.w3.org/TR/WCAG20/#media-equiv-real-time-captions
-.. _1.2.5 Audio Description (Prerecorded): http://www.w3.org/TR/WCAG20/#media-equiv-audio-desc-only
+.. _1.2.4 Captions (Live): https://www.w3.org/TR/WCAG20/#media-equiv-real-time-captions
+.. _1.2.5 Audio Description (Prerecorded): https://www.w3.org/TR/WCAG20/#media-equiv-audio-desc-only
 .. _1.3.4 Orientation: https://www.w3.org/TR/WCAG21/#orientation
 .. _1.3.5 Identify Input Purpose: https://www.w3.org/TR/WCAG21/#identify-input-purpose
-.. _1.4.3 Contrast (Minimum): http://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
-.. _1.4.4 Resize text: http://www.w3.org/TR/WCAG20/#visual-audio-contrast-scale
-.. _1.4.5 Images of Text: http://www.w3.org/TR/WCAG20/#visual-audio-contrast-text-presentation
+.. _1.4.3 Contrast (Minimum): https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
+.. _1.4.4 Resize text: https://www.w3.org/TR/WCAG20/#visual-audio-contrast-scale
+.. _1.4.5 Images of Text: https://www.w3.org/TR/WCAG20/#visual-audio-contrast-text-presentation
 .. _1.4.10 Reflow: https://www.w3.org/TR/WCAG21/#reflow
 .. _1.4.11 Non-text Contrast: https://www.w3.org/TR/WCAG21/#non-text-contrast
 .. _1.4.12 Text Spacing: https://www.w3.org/TR/WCAG21/#text-spacing
 .. _1.4.13 Content on Hover or Focus: https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus
-.. _2.4.5 Multiple Ways: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-mult-loc
-.. _2.4.6 Headings and Labels: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-descriptive
-.. _2.4.7 Focus Visible: http://www.w3.org/TR/WCAG20/#navigation-mechanisms-focus-visible
+.. _2.4.5 Multiple Ways: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-mult-loc
+.. _2.4.6 Headings and Labels: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-descriptive
+.. _2.4.7 Focus Visible: https://www.w3.org/TR/WCAG20/#navigation-mechanisms-focus-visible
 .. _2.4.11 Focus Not Obscured (Minimum): https://www.w3.org/TR/WCAG22/#focus-not-obscured-minimum
 .. _2.5.7 Dragging Movements: https://www.w3.org/TR/WCAG22/#dragging-movements
 .. _2.5.8 Target Size (Minimum): https://www.w3.org/TR/WCAG22/#target-size-minimum
-.. _3.1.2 Language of Parts: http://www.w3.org/TR/WCAG20/#meaning-other-lang-id
-.. _3.2.3 Consistent Navigation: http://www.w3.org/TR/WCAG20/#consistent-behavior-consistent-locations
-.. _3.2.4 Consistent Identification: http://www.w3.org/TR/WCAG20/#consistent-behavior-consistent-functionality
-.. _3.3.3 Error Suggestion: http://www.w3.org/TR/WCAG20/#minimize-error-suggestions
-.. _3.3.4 Error Prevention (Legal, Financial, Data): http://www.w3.org/TR/WCAG20/#minimize-error-reversible
+.. _3.1.2 Language of Parts: https://www.w3.org/TR/WCAG20/#meaning-other-lang-id
+.. _3.2.3 Consistent Navigation: https://www.w3.org/TR/WCAG20/#consistent-behavior-consistent-locations
+.. _3.2.4 Consistent Identification: https://www.w3.org/TR/WCAG20/#consistent-behavior-consistent-functionality
+.. _3.3.3 Error Suggestion: https://www.w3.org/TR/WCAG20/#minimize-error-suggestions
+.. _3.3.4 Error Prevention (Legal, Financial, Data): https://www.w3.org/TR/WCAG20/#minimize-error-reversible
 .. _3.3.8 Accessible Authentication (Minimum): https://www.w3.org/TR/WCAG22/#accessible-authentication-minimum
 .. _4.1.3 Status Messages: https://www.w3.org/TR/WCAG21/#status-messages
 

diff --git a/adding_content/adding_content.rst b/adding_content/adding_content.rst
@@ -0,0 +1,32 @@
+.. _adding_content:
+
+Adding and syncing content
+==========================
+
+A Simplifier project is, in effect, a small FHIR server. There are several ways to get FHIR content into it, ranging from a one-off manual upload to fully automated synchronization. Pick the approach that fits how your team works:
+
+- :doc:`Web interface <upload-resources>`: add resources directly in Simplifier, through the IG **Editor**, the **File manager**, or by uploading individual resources. Best for quick, ad-hoc changes.
+- :doc:`FHIR API and project ZIP <api>`: every project exposes a FHIR API (and a downloadable ZIP) you can use to read and manage its contents programmatically. Best for scripted or custom integrations.
+- :doc:`GitHub <github>`: a webhook keeps a GitHub branch synced one-way into the project. Best when git is your source of truth and you want changes to flow in automatically on push. For :doc:`other git hosts <other-git-repositories>` such as Azure DevOps or GitLab, use a Firely Terminal pipeline.
+- :doc:`Forge <forge>`: syncs an entire local folder to a linked project (not just the profiles Forge created), with a conflict-resolution wizard. Best for data modelers working in Forge.
+- :doc:`Firely Terminal <firely-terminal>`: fast command-line sync that also runs on macOS and in CI/CD pipelines. Best for automation and power users.
+
+However you add resources, you can control how Simplifier renders them: :doc:`metadata expressions <metadata-expressions>` let you define automatically which fields Simplifier uses as a resource's title, description, URL key, workflow, and file path.
+
+**Agree on a team workflow.** Changes in Simplifier do not automatically propagate to your git repository; syncing always requires explicit steps. Treat the git repository as the source of truth:
+
+- Make changes locally, commit and push to git, then sync or publish them to Simplifier.
+- If you edit in the Simplifier IG editor, first sync or download those changes back to your local repository and commit them.
+- Agree on conflict-resolution rules up front (for example, always **TakeLocal** if you work with a git repository).
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   upload-resources
+   api
+   forge
+   firely-terminal
+   github
+   other-git-repositories
+   metadata-expressions
diff --git a/features/api.rst → adding_content/api.rst b/features/api.rst → adding_content/api.rst
@@ -81,9 +81,9 @@ Basic Auth directly. However, going forward we recommend the JWT authentication
 Features API
 """"""""""""
 
-The Simplifier Features API allows you to retrieve feautures for your account on the
-platform, like the feautures your plan gives you access to, the projects you have 
-accesss to and the files within them.
+The Simplifier Features API allows you to retrieve features for your account on the
+platform, like the features your plan gives you access to, the projects you have 
+access to and the files within them.
 
 The currently supported calls include:
 
@@ -109,7 +109,7 @@ The API for **public FHIR packages** is documented and can be tested directly on
 
 The API for **private FHIR packages** is exactly the same as the public API, but requires authentication. You can use the JWT token you retrieved in the previous section to authenticate your requests. Additionally, it uses the :ref:`package feed <package_feeds>` Urlkey as the base URL for the API, for example ``https://packages.simplifier.net/feeds/mySimplifierPackageFeedUrlkey/`` for a package feed with the URL key ``mySimplifierPackageFeedUrlkey``.
 
-**Note**: It is not possible to create a package using the API. For more information on how to create a package please read our `documentation <../data_governance_and_quality_control/simplifierPackages.html#publish-packages>`_ on packages. 
+**Note**: It is not possible to create a package using the API. For more information on how to create a package please read our `documentation <../package_releases/simplifierPackages.html#create-releases>`_ on packages. 
 
 NPM compatible endpoint
 =======================

diff --git a/adding_content/firely-terminal.rst b/adding_content/firely-terminal.rst
@@ -0,0 +1,49 @@
+Firely Terminal synchronization
+===============================
+
+`Firely Terminal <https://docs.fire.ly/projects/Firely-Terminal/>`_ is Firely's command-line tool for working with FHIR. You can use it to synchronize resources between your local project and Simplifier.
+
+It is a good fit when you want synchronization that is:
+
+- **Quick and effective** for everyday use from the command line.
+- **Cross-platform**: it also runs on macOS (and Linux).
+- **Automatable**: it runs in CI/CD pipelines, so you can sync or publish as part of an automated workflow (see :doc:`other git repositories <other-git-repositories>` for an Azure DevOps example).
+
+Connect to your project
+-----------------------
+
+First, log in and link your local folder to a Simplifier project. You only have to do this once per folder. At link time you can already set a conflict-resolution strategy, so that later syncs resolve conflicts automatically without prompting.
+
+.. code:: bash
+
+   fhir login email=<your-email> password=<your-password>
+   fhir project link <project-url-key> --strategy TakeLocal
+
+The ``--strategy`` option determines how conflicts are resolved: ``TakeLocal`` always keeps your local version, ``TakeRemote`` always keeps the version on Simplifier.
+
+Synchronize
+-----------
+
+Once the folder is linked, you can move resources between your local folder and Simplifier:
+
+- ``fhir project sync``: synchronize your local folder with Simplifier, applying the conflict strategy you configured.
+- ``fhir project push``: send your local resources to Simplifier.
+- ``fhir project pull``: fetch the resources from Simplifier into your local folder.
+
+.. code:: bash
+
+   fhir project sync
+   fhir project push
+   fhir project pull
+
+Conflicts
+---------
+
+If your source of truth is a git repository, you do not have to be afraid of conflicts: you can always overwrite what is on Simplifier by linking or syncing with ``--strategy TakeLocal``. Your committed git history remains the authoritative version, and Simplifier is brought in line with it.
+
+If you would rather review conflicts and see exactly what changed before resolving them, use :doc:`Forge <forge>` instead. Forge has a conflict-resolution wizard that gives you more insight into each change.
+
+Command reference
+-----------------
+
+For installation and the complete set of commands and options, see the `Firely Terminal command reference <https://docs.fire.ly/projects/Firely-Terminal/Command-Reference.html>`_.
diff --git a/...ty_control/simplifierForgeIntegration.rst → adding_content/forge.rst b/...ty_control/simplifierForgeIntegration.rst → adding_content/forge.rst
@@ -1,5 +1,5 @@
-Simplifier Forge Integration
-----------------------------
+Forge synchronization
+=====================
 
 Simplifier and our datamodelling tool Forge work hand in hand. With our new project synchronization feature this has become even easier. For more information on this feature please see our Forge documentation `here. <https://docs.fire.ly/projects/Forge/features/IntegrationwithSimplifier.html>`_
 
@@ -11,7 +11,7 @@ But there are certainly cases where you can accidentally overwrite each other’
 
 We do keep the history of resources, but first you will have to notice that something got lost.
 
-If you really want great collision detection it is probably best to connect your Simplifier project to a branch of a GitHub repository and collaborate in there: https://docs.fire.ly/projects/Simplifier/simplifierGithub.html. The drawbacks could be:
+If you really want great collision detection it is probably best to connect your Simplifier project to a branch of a GitHub repository and collaborate in there (see :doc:`github`). The drawbacks could be:
 
   - Git can be a bit complicated to work with.
   - The synchronization is one-way, from GitHub to Simplifier. Editing of Implementation Guides currently happens in Simplifier, so whenever you want those changes back to GitHub you will need to synchronise them from Simplifier to your local computer (with Forge or Firely Terminal) and then commit the changes back to GitHub.