Formatting edits for new theme

source/dev-docs/dev-faq/faq-contributing.rst

@@ -1,8 +1,8 @@
 .. _faq-contributing:
 
-************
+============
 Contributing
-************
+============
 
 We ❤️ contributions!
 
@@ -12,7 +12,6 @@ Do I need to be a professional developer or have coding experience to contribute
 ---------------------------------------------------------------------------------
 Absolutely not!  Contributions can be as simple as finding a typo in our docs, making a suggestion on GitHub, creating educational or promotional content, and the list goes on!  Everyone that wants to contribute can do so in some unique way.  Please don't hesitate to ***CONTACT LINK*** us for ideas if you're not sure where to begin.
 
-
 Expound the following into FAQs move to other dev-faq section if necessary:
 ---------------------------------------------------------------------------
 

source/dev-docs/dev-faq/faq-service-packaging.rst

@@ -1,8 +1,8 @@
 .. _faq-service-packaging:
 
-*********************
+=====================
 Service Packaging FAQ
-*********************
+=====================
 
 Do I need programming experience to package a service for EmbassyOS?
 --------------------------------------------------------------------

source/dev-docs/dev-faq/index.rst

@@ -1,8 +1,10 @@
-*************
-Developer FAQ
-*************
+.. _dev-faq:
 
-An overview of EmbassyOS general capabilities.
+=============
+Developer FAQ
+=============
+
+Frequently Asked Questions by and for developers.  If you have a suggestion, please use the Github link at the top of the page.
 
 .. toctree::
   :maxdepth: 2

source/dev-docs/packaging-example.rst

@@ -1,18 +1,18 @@
 .. _packaging-example:
 
-*************************
+=========================
 Service Packaging Example
-*************************
+=========================
 
 A rough walkthrough of how to package a service using our example `hello-world-wrapper <https://github.com/Start9Labs/hello-world-wrapper>`_.
 
 Welcome!  The following guide will provide the prerequisites, introduce a brief overview of the packaging process, use an example demonstrating how to package a service, and finally describe the submission process.  This essentially describes how you can take an existing app (or one you have written yourself), and wrap it up such that it can be added to an EmbassyOS Marketplace!
 
 Pre-requisites
-==============
+--------------
 
 EmbassyOS (EOS)
----------------
+...............
 
 It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service.
 
@@ -22,7 +22,7 @@ There are 3 options for this:
     #. :ref:`Purchse <purchasing>` a device or copy of the OS
 
 Development Environment
------------------------
+.......................
 
 Once you have EOS installed, you'll want to set up your development system with the necessary software.
 
@@ -38,10 +38,10 @@ The following are recommended:
     #. rust-musl-cross (***PLACEHOLDER FOR NEW MUSL-CROSS REPO***) (For cross compiling Rust to Alpine, not needed otherwise)
 
 Overview
-========
+--------
 
 Components
-----------
+..........
 
 Simply, the package is made up of the following parts:
     1. Image - Each service is running in a Docker image.  Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
@@ -54,7 +54,7 @@ Simply, the package is made up of the following parts:
 Check :ref:`here <service_package_overview>` for a detailed overview of package components.
 
 Service Wrapper Repo and Submodules
------------------------------------
+...................................
 
 See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository.
 
@@ -67,12 +67,12 @@ Simply run:
   git submodule add <link_to_source_project>
 
 Example - Hello World
-=====================
+---------------------
 
 Okay, let's actually package a service!  For this example, we're going to use an example service `Hello World <https://github.com/Start9Labs/hello-world>`_.  This repository can also be used as a template to quickly get started with your service.  This will give a good overview of service packaging, but obviously your app will be different.  This will assume a Linux development environment with all the recommended dependencies listed above.  To get started quickly, we'll use Start9's wrapper template.
 
 Clone the Template Repo and Edit the Manifest
----------------------------------------------
+.............................................
 
 1. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
 
@@ -86,7 +86,7 @@ Clone the Template Repo and Edit the Manifest
 3. Edit the ``manifest`` file.  This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style.  You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
 
 Manifest example
-----------------
+................
 
 .. code-block:: yaml
 
@@ -247,7 +247,7 @@ Note the ``dependencies`` and ``volumes`` sections, which may access another ser
 For details on all the different possible dependency, type, and subtype definitions available for the ``manifest`` file, please see :ref:`here <service_manifest>`.
 
 Edit the Dockerfile and Entrypoint
-----------------------------------
+..................................
 
 Next, it's time to edit the ``Dockerfile``.  This defines how to build the image for the package by declaring the environment, building stages, and mounting the package to the volume specified in the ``manifest``.
 
@@ -318,7 +318,7 @@ Next, it's time to edit the ``Dockerfile``.  This defines how to build the image
 For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/docker_entrypoint.sh>`_.  Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here <https://docs.start9.com/contributing/services/docker.html>`_.
 
 Makefile (Optional)
--------------------
+...................
 
 Here, we will create a ``Makefile``, which is optional, but recommended as it outlines the build and streamlines additional developer contributions.  Alternatively, you could use any other build orchestration tool, such as ``nix``, ``bash``, ``python``, ``perl``, ``ruby``, etc instead of ``make``.
 
@@ -370,7 +370,7 @@ Our example ``Makefile`` is agin fairly simple for Hello World.  Let's take a lo
 For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
 
 Service Config Specification and Rules
---------------------------------------
+......................................
 
 Most self-hosted packages require a configuration.  With EmbassyOS, these config options are provided to the user in a friendly GUI, and invalid configs are not permitted.  This allows the user to manage their software without a lot of technical skill, and minimal risk of borking their software.  Two files are created in this process:
 
@@ -482,14 +482,14 @@ In our example, there is *no need* for a ``config_rules`` file.  This is because
 Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config.
 
 Properties
-----------
+..........
 
 Next we need to create the Properties section for our package, to display any relevant info.  The result of this step is a ``stats.yaml`` file, which is only populated at runtime.  These commands will be issued in the ``docker_entrypoint`` file (or ``configurator``, if you are using one).
 
 ***STATS.YAML IS APPARENTLY BEING DEPRECATED, THIS SECTION NEEDS COMMENT***
 
 Instructions
-------------
+............
 
 Instructions are the basic directions or any particular details that you would like to convey to the user to help get them on their way.  Each wrapper repo should contain a ``docs`` directory which can include anything you'd like, but specifically if you include an ``instructions.md`` file, formatted in Markdown language, it will be displayed simply for the user as shown below.
 
@@ -498,12 +498,12 @@ Instructions are the basic directions or any particular details that you would l
 You can find the ``instructions.md`` file for Embassy Pages `here <https://github.com/Start9Labs/embassy-pages-wrapper/tree/master/docs>`_ if you are interested.
 
 Backups
--------
+.......
 
 Everything in the root folder of the mounted system directory will be stored in an EOS backup.  If you want to ignore any particular files for backup, you can create a ``.backupignore`` file and add the relative paths of any directories you would like ignored.
 
 Submission Process
-------------------
+..................
 
 When you have built and tested your project for EmbassyOS, please send Start9 a submission with the project repository to dev@start9labs.com. After being reviewed for security and compatibility, the service will be deployed to the marketplace and available for all EmbassyOS users to download.
 

source/dev-docs/service-packaging/backups.rst

@@ -1,8 +1,8 @@
 .. _service_backups:
 
-***************
+===============
 Service Backups
-***************
+===============
 
 Everything within the root of the mounted volume directory will be stored in an EmbassyOS backup. This includes the config (config.yaml) and properties (stats.yaml) files, as well as any other persisted data within the volume directory. 
 
@@ -12,7 +12,7 @@ In this case, create a `.backupignore` file. This file contains a list of relati
 
 
 Example
-=======
+-------
 
 The `btcpayserver wrapper <https://github.com/Start9Labs/btcpayserver-wrapper/blob/master/configurator/src/templates/.backupignore.templates>`_ demonstrates a good use of a backupignore template.
 

source/dev-docs/service-packaging/config.rst

@@ -1,11 +1,11 @@
 .. _service_config:
 
-****************************
+============================
 Service Config Specification
-****************************
+============================
 
 Overview
-========
+--------
 
 Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's configuration will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
 
@@ -24,10 +24,10 @@ For example, if the user chooses config option A, then config option B must be b
 .. _config_spec:
 
 Config Spec
-===========
+-----------
 
 Overview
---------
+........
 
 .. figure:: /_static/images/service/bitcoin_config.png
   :width: 80%
@@ -49,7 +49,7 @@ The neat part about this file is that each ValueSpec type gets translated into a
 Another advantage is the ability to define default values. These values automatically get populated if the user selects the ``Default`` option when setting up a service in ``Needs Config`` state. This is super convenient for users who want to get up and running quickly.
 
 Types
------
+.....
 
 ConfigSpec Type:
 
@@ -60,7 +60,7 @@ ConfigSpec Type:
     ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details)
 
 Implementation Guide
---------------------
+....................
 
 The following section contains implementation specifications for the ``config_spec.yaml`` file.
 
@@ -506,7 +506,7 @@ Example:
 .. _config_rules:
 
 Config Rules
-============
+------------
 
 This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules. 
 

source/dev-docs/service-packaging/docker.rst

@@ -1,11 +1,11 @@
 .. _service_docker:
 
-******************
+==================
 Service Dockerfile
-******************
+==================
 
 Dockerfile
-==========
+----------
 
 This purpose of the Dockerfile is to define how to build the image for the service. It declares the environment and building stages.
 The Dockerfile is responsible for mounting the service application to whatever volume the manifest specifies, typically ``/root/.<service-id>``.
@@ -23,14 +23,14 @@ For instance:
 We recommended using ``alpine`` since it produces the smallest image. We try to keep the image under 100MB when possible.
 
 Entry-point
-===========
+-----------
 
 The ``docker_entrypoint.sh`` defines what to do when the service application starts.
 
 It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands for EmbassyOS.
 
 Example
-=======
+-------
 
 The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Dockerfile>`_ features a well defined Dockerfile, for example.
 

source/dev-docs/service-packaging/index.rst

@@ -1,6 +1,8 @@
-*******************************
+.. _service-packaging-spec:
+
+===============================
 Service Packaging Specification
-*******************************
+===============================
 
 Welcome! If you are here, you are interested in becoming part of the mission to change the future of personal computing. This guide will take you through the process of packaging a service for EmbassyOS, a novel, self-hosted, sovereign computing platform.
 

source/dev-docs/service-packaging/instructions.rst

@@ -1,8 +1,8 @@
 .. _service_instructions:
 
-************************************
+====================================
 Service Instructions & Documentation
-************************************
+====================================
 
 Within each wrapper repository should exist a ``docs`` directory. This folder should include any pertinent documentation, instructions, external integrations, or other details about the service that users or developers might find relevant.
 
@@ -13,7 +13,7 @@ If an ``instructions.md`` file is included, this markdown formatted file will be
   :alt: Bitcoin Instructions
 
 Example
-=======
+-------
 
 The `bitcoind wrapper <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs>`_ demonstrates a good use of instructions and external integrations.
 

source/dev-docs/service-packaging/makefile.rst

@@ -1,8 +1,8 @@
 .. _service_makefile:
 
-****************
+================
 Service Makefile
-****************
+================
 
 .. note::
 
@@ -20,7 +20,7 @@ This purpose of this file is to:
 - Package ``config_rules.yaml``, ``config_spec.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoking ``appmgr``.
 
 Example
-=======
+-------
 
 The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Makefile>`_ features a well defined Makefile, for example.
 

source/dev-docs/service-packaging/manifest.rst

@@ -1,11 +1,11 @@
 .. _service_manifest:
 
-****************
+================
 Service Manifest
-****************
+================
 
 Overview
-========
+--------
 
 This file describes the service and it's requirements. It is used to:
 
@@ -22,13 +22,14 @@ There is nothing you need to do as a developer to set up Tor for running a servi
 The manifest is also responsible for outlining service :ref:`dependencies <dependencies>`. By defining rules using the :ref:`EmbassyOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. EmbassyOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
 
 Formatting
-==========
+----------
 
 - Serialization language:``.yaml``
 - Case style: ``kebab-case``
 
 Type definitions
-================
+----------------
+
 Below are the types and sub-type definitions, with necessary elaborations. Any item that contains ``Option<>`` is an optional field.
 
 .. code:: yaml
@@ -84,7 +85,7 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
 .. _dependencies:
 
 Dependencies
-============
+------------
 
 Many services depend on other libraries and services on EmbassyOS (such as Bitcoin), sometimes even a particular version of those services, which need to be specified by the developers so that EmbassyOS can handle installing these dependencies under the hood.
 
@@ -121,7 +122,7 @@ The service ``btc-rpc-proxy`` is a dependency of the service ``c-lightning``. ``
     Dependency config rules are processed in order.
 
 Type definitions
-----------------
+................
 
 Types for ``manifest.yaml`` fields:
 
@@ -174,7 +175,7 @@ Types for ``manifest.yaml`` fields:
 :raw-html:`<br />`
 
 Examples
---------
+........
 
 Actual ``manifest.yaml`` files for existing services:
 

source/dev-docs/service-packaging/overview.rst

@@ -1,20 +1,20 @@
 .. _service_package_overview:
 
-************************
+========================
 Service Package Overview
-************************
+========================
 
 There are several main components that comprise a service package for EmbassyOS. This overview will introduce them and following sections will dive into technical specifics.
 
 First, let's get your system setup with the necessary software dependencies.
 
 Environment Setup
-=================
+-----------------
 
 At minimum, ``docker``, ``docker-buildx``, and ``appmgr`` are required. The rest of the recommendations serve to optimize the build process.
 
 Recommended Dependencies
-------------------------
+........................
 
     `docker <https://docs.docker.com/get-docker>`_
 
@@ -31,10 +31,10 @@ Recommended Dependencies
     `musl <https://github.com/Start9Labs/rust-musl-cross>`_
 
 Package Components
-==================
+------------------
 
 Image
------
+.....
 
 Each service boils down to a Docker image. We're not going to dive into Docker specifics in this guide, since there exists tons of `resources <https://docs.docker.com/>`_ for developing with this containerization tool.
 
@@ -43,7 +43,8 @@ Because the service ultimately runs on a Raspberry Pi, the created Docker image
 The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
 
 Volume
-------
+......
+
 Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates.
 
 The volume directory (for seeding data into the volume) is typically: ``/root/volumes/<service-id>``.
@@ -52,7 +53,7 @@ The volume directory (for seeding data into the volume) is typically: ``/root/vo
     Any files that are in the image at the volume path will be overwritten when a backup restore occurs.
 
 Dependencies
-------------
+............
 
 When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat.
 
@@ -65,7 +66,7 @@ The key to making the system work is a new, domain-specific-language (DSL) and s
 This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <dependencies>` key in the service manifest.
 
 Manifest
---------
+........
 
 This file describes the service and its requirements. It is used to:
 
@@ -80,21 +81,21 @@ For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/bl
 There is nothing you need to do as a developer to enable the service to run over Tor. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated and an Nginx server configured (if a client application) when the service is installed. Just define which version of Tor your service needs in this manifest file!
 
 Config
-------
+......
 
 Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's :ref:`configuration <service_config>` will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
 
 With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and configuration dependencies.
 
 .s9pk Bundle
-------------
+............
 
 The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_. Each new version release should include the updated version of these files re-bundled into a new binary. This is the file that will be downloaded from the marketplace. Upon user initiation, EmbassyOS then un-packages and installs the service.
 
 Hello World Example
--------------------
+...................
 
-For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapper>`_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub.
+For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapper>`_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub.  For a detailed walkthrough of this example, please see the :ref:`Packaging Example<packaging-example>`.
 
 
 .. role:: raw-html(raw)

source/dev-docs/service-packaging/properties.rst

@@ -1,8 +1,8 @@
 .. _service_properties:
 
-******************
+==================
 Service Properties
-******************
+==================
 
 The output of this step is a file titled ``stats.yaml``. This file contains a mapping of the values that will be displayed in the ``Properties`` section in a service's menu.
 
@@ -15,7 +15,7 @@ The output of this step is a file titled ``stats.yaml``. This file contains a ma
 Due to the fact that config variables are only available when the service is running, this file can only be populated at runtime. In services Start9 has wrapped or created, we typically handle this in ``configurator/src/main.rs``. This file is essentially a script that acquires the necessary values at runtime from config (eg. ``/root/.lnd/start9/config.yaml``), and dynamically populating them to the ``stats.yaml`` file, marking each value with the appropriate keys for UI display (ie. masked or copyable). Running the configurator is typically included in the ``docker_entrypoint.sh`` file.
 
 Example
-=======
+-------
 
 A good example of the configurator producing the ``stats.yaml`` file can be found `here <https://github.com/Start9Labs/lnd-wrapper/blob/master/configurator/src/main.rs>`_.
 

source/dev-docs/service-packaging/wrapper.rst

@@ -1,8 +1,8 @@
 .. _service_wrapper:
 
-***************
+===============
 Service Wrapper
-***************
+===============
 
 Each service is bound with a wrapper repository, which contains everything you need to build a service.
 
@@ -17,7 +17,7 @@ The purpose of this repo is:
 - symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root, if included
 
 File Structure
-==============
+--------------
 
 The project structure should be used as a model:
 
@@ -35,7 +35,7 @@ The project structure should be used as a model:
     └── manifest.yaml
 
 Submodule
-==========
+---------
 
 `Git submodules <https://www.git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allow use of another project while in the working project directory. Setting up this feature enables linking of the source service repository so that its context is available.
 

source/index.rst

@@ -8,6 +8,7 @@ Here you will find guidance and information about Embassy personal server and it
 
 EmbassyOS is designed to work out of the box with a minimal setup and immediate practicality.  That being said, there are a great many different use-cases and utilities that can be added at your convenience.  You can get started right away with :ref:`Initial Setup <initial-setup>`.  In the `User Manual <link>`, you will find information on what EmbassyOS can do for you, as well as configuration and customization options.  Use our `Knowledgebase <link>` to learn more about the technologies behind Embassy, including Frequently Asked Questions.  When you're ready to build, please check out our `Developer Docs <link>`.  Please don't hestitate to `Contact Us <https://start9.com/contact>`_ if you have any issues, questions, or suggestions that are not covered here.
 
+=================
 Table of Contents
 =================
 

source/knowledgebase/concepts/index.rst

@@ -2,7 +2,7 @@
 Concepts
 ========
 
-An overview of EmbassyOS general capabilities.
+An overview of the ideas and technologies surrounding Start9 Labs and Embassy
 
 .. toctree::
   :maxdepth: 2

source/knowledgebase/concepts/open-source.rst

@@ -1,8 +1,8 @@
 .. _open-source:
 
-***********
+===========
 Open Source
-***********
+===========
 
 The Internet itself was built on free and publicly available code, with the values of collaboration, peer review, communication, and openness built into its very foundation. This decentralized model evolved into the open source movement, which uses these values to discover new ways to solve problems across boundaries and industries.
 

source/knowledgebase/concepts/start9.rst

@@ -1,15 +1,15 @@
 .. _start9:
 
-***********
+===========
 Start9 Labs
-***********
+===========
 
 Start9 Labs is a small, but rapidly growing team of passionate builders.  We are based in Denver, Colorado, but have team members around the world.
 
 .. _start9-origin:
 
 "The Origin of “Start9”
-=======================
+-----------------------
 
 Pokemon is a game for Gameboy. Twitch is a live video streaming app. “Twitch Plays Pokemon” was a popular phenomenon where Twitch users would collaborate to play a SHARED game of Pokemon on Gameboy. Here’s how it worked:
 

source/knowledgebase/faq/faq-basic-use.rst

@@ -1,8 +1,8 @@
 .. _faq-basic-use:
 
-*************
+=============
 Basic Use FAQ
-*************
+=============
 
 Is it easy to use?
 ------------------

source/knowledgebase/faq/faq-bitcoin.rst

@@ -1,8 +1,8 @@
 .. _faq-bitcoin:
 
-***********
+===========
 Bitcoin FAQ
-***********
+===========
 
 Why does the Bitcoin service take so long to be ready?
 ------------------------------------------------------

source/knowledgebase/faq/faq-embassy.rst

@@ -1,8 +1,8 @@
 .. _faq-embassy:
 
-***********
+===========
 Embassy FAQ
-***********
+===========
 
 Can I run EmbassyOS on a VPS or VM?
 -----------------------------------

source/knowledgebase/faq/faq-general.rst

@@ -1,8 +1,8 @@
 .. _faq-general:
 
-***********
+===========
 General FAQ
-***********
+===========
 
 What is Start9Labs?
 -------------------

source/knowledgebase/faq/faq-lightning.rst

@@ -1,8 +1,8 @@
 .. _faq-lightning:
 
-*************************
+=========================
 The Lightning Network FAQ
-*************************
+=========================
 
 Why would I want to run a lightning node?
 -----------------------------------------

source/knowledgebase/faq/faq-services.rst

@@ -1,8 +1,8 @@
 .. _faq-services:
 
-************
+============
 Services FAQ
-************
+============
 
 My Embassy is set up, now what?
 -------------------------------

source/knowledgebase/faq/faq-troubleshooting.rst

@@ -1,8 +1,8 @@
 .. _faq-troubleshooting:
 
-*****************************
+=============================
 Setup and Troubleshooting FAQ
-*****************************
+=============================
 
 What do I do first?
 -------------------

source/knowledgebase/faq/index.rst

@@ -1,8 +1,8 @@
-***
+===
 FAQ
-***
+===
 
-An overview of EmbassyOS general capabilities.
+Frequently Asked Questions from Embassy users
 
 .. toctree::
   :maxdepth: 2

source/user-manual/configuration/index.rst

@@ -1,8 +1,8 @@
-*************
+=============
 Configuration
-*************
+=============
 
-An overview of EmbassyOS general capabilities.
+Configuration, setup guides, and known limitations are provided here by device
 
 .. toctree::
   :maxdepth: 2

source/user-manual/configuration/lan-setup/index.rst

@@ -1,13 +1,10 @@
 .. _lan-setup:
 
-************
+============
 Local Access
-************
+============
 
-.. warning::
-  This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
-
-Once you have completed the above guide, select your device's operating system below:
+When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access<lan>` is much faster and will allow access to your data, even with no Internet connection.
 
 .. toctree::
   :maxdepth: 2

source/user-manual/configuration/lan-setup/lan-ios.rst

@@ -1,5 +1,80 @@
 .. _lan-ios:
 
-***
+===
 iOS
-***
+===
+
+#. Navigate back to the `Start9 Setup App <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_. 
+
+#. Select your claimed Embassy to view the setup results.
+
+#. Find the "LAN (advanced)" menu item at the bottom of the Setup App screen.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_setup_app_complete.png
+    :width: 70%
+    :alt: Setup app complete
+
+    Completed Setup App screen
+
+#. Select the "Embassy Local Root CA" menu item. Clicking this will prompt you to “Save to device”.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_setup_app_advanced.png
+    :width: 70%
+    :alt: Setup app advanced menu
+
+    Setup App advanced menu
+
+#. You will be directed to a page in your default browser indicating next steps and that the profile has been successfully downloaded. 
+
+   .. note::
+        If you have changed the default browser from Safari to Brave, the following auto save certificate to device flow will *not* work. Safari, Firefox, and Chrome work as expected. We recommend you temporarily use one of these browsers to complete this action.
+
+#. Be sure to complete all steps in this process! These steps are also outlined below.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_certificate_install_page.png
+    :width: 70%
+    :alt: Certificate install page
+
+    Select "Allow" on the certificate install page
+
+#. Go to Settings on your iOS device.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_ipad_general_settings.png
+    :width: 70%
+    :alt: General settings
+
+    General settings
+
+#. Navigate to *General > Profile(s) > Downloaded Profile > Install*.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_ipad_profiles.png
+    :width: 70%
+    :alt: Profiles
+
+    Profiles view
+
+   .. figure:: /_static/images/ssl/mobile/ssl_ipad_install_profile.png
+    :width: 70%
+    :alt: Install profile
+
+    Select "Install" for Embassy Local Root CA
+
+#. Select “yes” to any warning prompts.
+
+#. Next, navigate to *General > About > Certificate Trust Settings*.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_ipad_cert_trust_settings.png
+    :width: 70%
+    :alt: Certificate trust settings
+
+    Select Certificate Trust Settings (scroll all the way down)
+
+#. Enable full trust for root certificates.
+
+   .. figure:: /_static/images/ssl/mobile/ssl_ipad_cert_trust.png
+    :width: 70%
+    :alt: Enable full trust
+
+    Toggle to enable full trust for root certificates. "Continue" when warning prompts.
+
+#. Test that this process worked successfully by navigating to the LAN address provided in the Setup App. You should no longer see warnings about the security of this site in your browser. We recommend using Start9’s own `Consulate browser <https://apps.apple.com/us/app/consulate/id1528124570>`_ for a faster and better experience.

source/user-manual/configuration/lan-setup/lan-linux.rst

@@ -1,5 +1,27 @@
 .. _lan-linux:
 
-*****
+=====
 Linux
-*****
+=====
+
+Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
+
+#. Visit your Embassy at its Tor Address.
+
+#. Navigate to --> Embassy --> Connect Over LAN
+
+   .. figure:: /_static/images/embassy_lan_setup.png
+    :width: 90%
+    :alt: LAN setup menu item
+
+    Select the "Connect over LAN" menu item
+
+#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
+
+   .. figure:: /_static/images/secure_lan_setup_page.png
+    :width: 90%
+    :alt: LAN setup page
+
+    Select the "Root Certificate Authority" sub menu
+
+Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

source/user-manual/configuration/lan-setup/lan-mac.rst

@@ -1,15 +1,65 @@
 .. _lan-mac:
 
-***
+===
 Mac
-***
+===
 
-.. _lan-new-mac:
+#. Visit your Embassy at its Tor Address.
 
-Newer Mac (M1)
-==============
+#. Navigate to --> Embassy --> Connect Over LAN
 
-.. _lan-old-mac:
+   .. figure:: /_static/images/embassy_lan_setup.png
+    :width: 90%
+    :alt: LAN setup menu item
 
-Older Mac
-=========
+    Select the "Connect over LAN" menu item
+
+#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
+
+   .. figure:: /_static/images/secure_lan_setup_page.png
+    :width: 90%
+    :alt: LAN setup page
+
+    Select the "Root Certificate Authority" sub menu
+
+#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
+
+   .. figure:: /_static/images/secure_lan_setup_prompt.png
+    :width: 90%
+    :alt: LAN setup prompt
+
+    Open with "Keychain Access" and select "OK"
+
+#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
+
+   .. figure:: /_static/images/ssl/macos/certificate_untrusted.png
+    :width: 90%
+    :alt: Keychain access import menu
+
+    Keychain access import menu
+
+#. If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it.
+
+#. Navigate to the "System" tab and find the certificate entitled “Embassy Local Root CA”.
+
+#. Double click on this certificate. A second window will pop up.
+
+#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “when using this certificate”.
+
+   .. figure:: /_static/images/ssl/macos/always_trust.png
+    :width: 90%
+    :alt: Keychain submenu
+
+    Select "Always trust" under SSL dropdown for Embassy Local CA
+
+#. Close this window and enter your password to apply the settings.
+
+#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access.
+
+   .. figure:: /_static/images/ssl/macos/certificate_trusted.png
+    :width: 90%
+    :alt: Keychain menu trusted certificate
+
+    Trusted Embassy Local CA certificate
+
+#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

source/user-manual/configuration/lan-setup/lan-windows.rst

@@ -1,5 +1,116 @@
 .. _lan-windows:
 
-*******
+=======
 Windows
-*******
+=======
+
+#. Install `Bonjour Print Services <https://support.apple.com/kb/DL999>`_ on your Windows machine. This is necessary in order to visit .local addresses on Windows.
+#. If you are having issues running Bonjour after installing, you might have had Bonjour previously installed. To fix:
+
+   #. Check out this video: https://www.youtube.com/watch?v=9ECCB3bqNDQ
+   #. Uninstall Bonjour completely via ``system settings -> remove programs``
+   #. Reinstall Bonjour Printer Driver package (download at https://support.apple.com/kb/DL999?locale=en_US)
+   #. Restart Windows
+   #. Note: Uninstalling Bonjour via the setup package seems to be not enough to solve the issue. Bonjour must be uninstalled via windows system settings.
+
+#. Visit your Embassy at its Tor Address.
+
+#. Navigate to --> Embassy --> Connect Over LAN
+
+   .. figure:: /_static/images/embassy_lan_setup.png
+    :width: 90%
+    :alt: LAN setup menu item
+
+    Select the "Connect over LAN" menu item
+
+#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
+
+   .. figure:: /_static/images/secure_lan_setup_page.png
+    :width: 90%
+    :alt: LAN setup page
+
+    Select the "Root Certificate Authority" sub menu download icon
+
+#. Select the option to save the *Embassy Local CA.crt* file.
+
+   .. figure:: /_static/images/ssl/windows/windows_download_cert.png
+    :width: 90%
+    :alt: LAN setup prompt
+
+    "Save file" when Opening Embassy Local CA.crt
+
+#. On your computer, right-click the “Start” menu and select “Run”.
+
+#. Type in “mmc” and click “OK”. When prompted on the “User Account Control” window, select “Yes” to allow this program to run.
+
+   .. figure:: /_static/images/ssl/windows/1_windows_mmc.png
+    :width: 90%
+    :alt: Windows MMC
+
+    Access the Windows Management Console
+
+#. When the Management Console opens, navigate to *File > Add/Remove Snap-in*.
+
+   .. figure:: /_static/images/ssl/windows/2_windows_console_root.png
+    :width: 90%
+    :alt: Windows Console Root
+
+    Add Snap-in from Console Root
+
+#. Select “Certificates” in the left side menu, then “Add”. This will open another window.
+
+   .. figure:: /_static/images/ssl/windows/3_windows_add_certificates.png
+    :width: 90%
+    :alt: Add Certificates
+
+    Add Certificates to selected snap-ins
+
+#. Select “Computer account” and click “Next. Leave defaulted options on the next screen and click “Finish”.
+
+#. When you return to the “Add or Remove Snap-ins” page, ensure “Certificates (Local Computer)” exists under “Console Root” in the “Selected snap-ins” section, then click “OK”.
+
+   .. figure:: /_static/images/ssl/windows/4_windows_selected_snapin.png
+    :width: 90%
+    :alt: Snap-in Selected
+
+    Certificates (Local Computer) is selected as snap-in
+
+#. In the left hand menu of the Management Console, navigate to Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
+
+   .. figure:: /_static/images/ssl/windows/5_windows_trusted_certificate_menu.png
+    :width: 90%
+    :alt: Certificates in Management Console
+
+    Access Certificates in Management Console
+
+#. Right click on “Certificates”, then navigate to *All Tasks > Import*.
+
+   .. figure:: /_static/images/ssl/windows/6_windows_import_cert.png
+    :width: 90%
+    :alt: Import certificate
+
+    Select "Import" from Certificates sub-menu
+
+#. Click “Next” on the first page of the Certificate Import Wizard, then browse to the location where you saved the downloaded certificate and click “Open”.
+
+   .. figure:: /_static/images/ssl/windows/7_windows_import_cert_wizard.png
+    :width: 90%
+    :alt: Import cert wizard
+
+    Add downloaded certificate int he Certificate Import Wizard
+
+#. On the “Certificate Store” window, ensure that it says “Trusted Root Certificate Authorities” and click “Next”.
+
+#. Select “OK” when the import is successful.
+
+#. Verify the Embassy Local Root CA certificate is in the “Certificates” folder.
+
+   .. figure:: /_static/images/ssl/windows/8_windows_successful_cert_install.png
+    :width: 90%
+    :alt: Successful cert install
+
+    Embassy Local Root CA imported into Certificate folder
+
+#. You can save the settings to the console if desired or cancel.
+
+#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

source/user-manual/configuration/limitations/index.rst

@@ -1,13 +1,10 @@
 .. _limitations:
 
-*****************
+=================
 Known Limitations
-*****************
+=================
 
-.. warning::
-  This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
-
-Once you have completed the above guide, select your device's operating system below:
+The following pages describe functionality that is known to be missing from certain platforms.  Please bother the appropriate company or developers until they have been remedied.
 
 .. toctree::
   :maxdepth: 2

source/user-manual/configuration/limitations/lim-android.rst

@@ -6,7 +6,7 @@ Android Known Limitations
 
 Local Access
 ------------
-Android does not have native support for :ref:`mDNS<mdns>` and therefore cannot resolve ``.local`` addresses.  This issue has been long known and can be tracked `here <https://issuetracker.google.com/issues/140786115>`_ (Google account required to view).
+Android does not have native support for :ref:`mDNS<mdns>` and therefore cannot resolve ``.local`` addresses.  This issue has been long known by Google, and can be tracked `here <https://issuetracker.google.com/issues/140786115>`_ (Google account required to view).
 
 Workarounds
 ...........

source/user-manual/configuration/limitations/lim-ios.rst

@@ -1,21 +1,21 @@
 .. _lim-ios:
 
-*********************
+=====================
 iOS Known Limitations
-*********************
+=====================
 
 Tor
-===
+---
 It is not currently possible to run Tor natively (in the background) on iOS.  The best chance for this functionality coming to iOS is via the `iCepa Project <https://github.com/iCepa>`_.
 
 Workarounds
------------
+...........
 The only way to use Tor on iOS is with apps that come with Tor built-in, such as :ref:`Zap Wallet <zap>`.
 
 Matrix
-======
+------
 The lack of Tor support on iOS means that Element/Matrix cannot be run on an iPhone in conjunction with your Embassy Matrix server, as that currently requires a Tor connection.  This will be fixed if `Element <https://github.com/vector-im/element-ios>` builds Tor into their app.
 
 Workarounds
------------
+...........
 None currently known.

source/user-manual/configuration/limitations/lim-linux.rst

@@ -1,7 +1,7 @@
 .. _lim-linux:
 
-***********************
+=======================
 Linux Known Limitations
-***********************
+=======================
 
 Linux has no known limitations in regard to Embassy.  Congratulations, Master Race...

source/user-manual/configuration/limitations/lim-mac.rst

@@ -1,6 +1,7 @@
 .. _lim-mac:
 
-*********************
+=====================
 Mac Known Limitations
-*********************
+=====================
 
+MacOS has no known limitations in regard to Embassy.

source/user-manual/configuration/limitations/lim-windows.rst

@@ -1,5 +1,5 @@
 .. _lim-windows:
 
-*************************
+=========================
 Windows Known Limitations
-*************************
+=========================

source/user-manual/configuration/tor-setup/tor-os/index.rst

@@ -1,13 +1,10 @@
 .. _tor-os:
 
-******************
+==================
 Using Tor Natively
-******************
+==================
 
-.. warning::
-  This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
-
-Once you have completed the above guide, select your device's operating system below:
+Select your Operating System to setup Tor to run in the background (natively) of any device that you might want to use to access your Embassy with remotely.
 
 .. toctree::
   :maxdepth: 2

source/user-manual/getting-started/device-guides/dg-android.rst

@@ -13,3 +13,5 @@ Tor Firefox Config (Connectivity)
 ---------------------------------
 
 `Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-android>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
+
+.. note:: Please see Android's :ref:`Known Limitations<lim-android>` to understand what is currently not possible on these devices

source/user-manual/getting-started/device-guides/dg-ios.rst

@@ -8,3 +8,5 @@ LAN Setup (Connectivity, Performance)
 -------------------------------------
 
 `Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-ios>`_ for a fast and secure connection while on your Embassy's local network.
+
+.. note:: Please see iOS's :ref:`Known Limitations<lim-ios>` to understand what is currently not possible on these devices

source/user-manual/getting-started/device-guides/dg-linux.rst

@@ -18,3 +18,5 @@ Tor Firefox Config (Connectivity)
 ---------------------------------
 
 `Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-linux>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
+
+.. note:: Please see Linux's :ref:`Known Limitations<lim-linux>` to understand what is currently not possible on these devices

source/user-manual/getting-started/device-guides/dg-mac.rst

@@ -18,3 +18,5 @@ Tor Firefox Config (Connectivity)
 ---------------------------------
 
 `Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-mac>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
+
+.. note:: Please see Mac's :ref:`Known Limitations<lim-mac>` to understand what is currently not possible on these devices

source/user-manual/getting-started/device-guides/dg-windows.rst

@@ -18,3 +18,5 @@ Tor Firefox Config (Connectivity)
 ---------------------------------
 
 `Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-windows>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
+
+.. note:: Please see Window's :ref:`Known Limitations<lim-windows>` to understand what is currently not possible on these devices

source/user-manual/getting-started/device-guides/index.rst

@@ -1,6 +1,6 @@
-**********************
+======================
 Device-Specific Guides
-**********************
+======================
 
 An overview of EmbassyOS general capabilities.
 

source/user-manual/getting-started/introduction.rst

@@ -1,8 +1,8 @@
 .. _introduction:
 
-************
+============
 Introduction
-************
+============
 
 :ref:`Embassy<embassy>` is a new kind of personal computer - one that sits quietly on your shelf and runs all day and night. It has no screen and no keyboard. You access your Embassy from anywhere in the world in total, trustless privacy, simply by visiting its unique Tor address (.onion URL) right from the browser.
 

source/user-manual/services/index.rst

@@ -1,3 +1,5 @@
+.. _services-index:
+
 ========
 Services - ***NEEDS UPDATING / SCREENS***
 ========

source/user-manual/troubleshooting/shoot-connection.rst

@@ -12,8 +12,8 @@ If you still cannot connect, you can log into your router (the directions for wh
 
 I am unable to reach Embassy via it's ``embassy-xxxxxxxx.local`` (LAN) address
 ------------------------------------------------------------------------------
-Make sure you have successfully followed the `LAN Setup<lan-setup>` instructions for your device.  If you still cannot connect, make sure you are on the same network using the solution above.  If you are able to visit your Embassy via its IP address, then something is wrong in your LAN Setup.  Keep in mind that different devices have different methods of resolving ``.local`` addresses, and some devices, such as `Android<lim-android>`, lack the ability at an OS level.
+Make sure you have successfully followed the :ref:`LAN Setup<lan-setup>` instructions for your device.  If you still cannot connect, make sure you are on the same network using the solution above.  If you are able to visit your Embassy via its IP address, then something is wrong in your LAN Setup.  Keep in mind that different devices have different methods of resolving ``.local`` addresses, and some devices, such as :ref:`Android<lim-android>`, lack the ability at an OS level.
 
 I am unable to reach Embassy via it's ``xxxxxxxxxxxxxxxxxx.onion`` (Tor) address
 --------------------------------------------------------------------------------
-First, attmept to connect using `The Tor Browser<tor-browser>`.  This is a good test because Tor Browser has Tor built in.  If you cannot reach your ``.onion`` with Tor Browser, reboot the Embassy by unplugging power and plugging it back in.  This will reset your Tor connection.  If you can reach via Tor Browser, but not with another browser, then follow the setup guides to run Tor on your device `Natively<tor-os>` and/or to `Configure Your Browser<tor-firefox>`.
+First, attmept to connect using :ref:`The Tor Browser<tor-browser>`.  This is a good test because Tor Browser has Tor built in.  If you cannot reach your ``.onion`` with Tor Browser, reboot the Embassy by unplugging power and plugging it back in.  This will reset your Tor connection.  If you can reach via Tor Browser, but not with another browser, then follow the setup guides to run Tor on your device :ref:`Natively<tor-os>` and/or to :ref:`Configure Your Browser<tor-firefox>`.

source/user-manual/tuning/advanced-config/index.rst

@@ -1,8 +1,8 @@
-**********************
+======================
 Advanced Configuration
-**********************
+======================
 
-An overview of EmbassyOS general capabilities.
+Custom options for folks that "know what they're doing."
 
 .. toctree::
   :maxdepth: 2

source/user-manual/tuning/advanced-config/ssh-setup.rst

@@ -1,13 +1,13 @@
 .. _ssh-setup:
 
-*********
+=========
 SSH Setup
-*********
+=========
 
 .. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.
 
 Connecting via CLI
-==================
+------------------
 
 #. Navigate to *Developer Options > SSH Keys*
 #. Click the ``+`` button in the lower right hand corner.
@@ -17,6 +17,6 @@ Connecting via CLI
     ssh pi@<LAN URL>
 
 Connecting via SSH on Windows, using PuTTY
-==========================================
+------------------------------------------
 
 One of our community members, @brewsbitcoin, has put together this guide for connecting via PuTTY on Windows: https://medium.com/@brewsbitcoin/ssh-to-start9-embassy-from-windows-4a4e17891b5a

source/user-manual/tuning/migrating.rst

@@ -8,3 +8,14 @@ From Umbrel
 -----------
 
 Dreadlocked
+
+======================
+Migrating From Embassy
+======================
+
+We hate to see you go, but respect your freedom to choose.  If you decide to use your hardware with different software, here are some guidelines.
+
+.. warning:: For obvious reasons, we cannot officially support anything that happens when you leave the Embassy ecosystem
+
+To Umbrel
+---------

source/user-manual/tuning/service-guides/bitcoin.rst

@@ -32,6 +32,11 @@ You can also drop into a shell using::
 
 and then enter ``bitcoin-cli`` commands.  When you are finished, simply type ``exit``.
 
+.. _electrum:
+
+Electrum
+--------
+
 .. _fully-noded:
 
 FullyNoded
@@ -46,3 +51,13 @@ Sparrow
 
 Specter
 -------
+
+.. _trezor:
+
+Trezor
+------
+
+.. _ledger:
+
+Ledger Live
+-----------

source/user-manual/tuning/service-guides/lightning.rst

@@ -1,6 +1,25 @@
 .. _lightning:
 
-*********
+=========
 Lightning
-*********
+=========
 
+.. _rtl:
+
+Ride the Lightning
+------------------
+
+.. _thunderhub:
+
+Thunderhub
+----------
+
+.. _zap:
+
+Zap
+---
+
+.. _zeus:
+
+Zeus
+----

source/user-manual/walkthrough/index.rst

@@ -1,3 +1,5 @@
+.. _walkthrough:
+
 ===========
 Walkthrough
 ===========