commit e2eb0976c75b57e9f9ea49b13086c17cea982150
author Jeroen van Meeuwen <vanmeeuwen@apheleia-it.ch> Mon Jul 15 09:14:32 2024 +0200
committer Jeroen van Meeuwen <vanmeeuwen@apheleia-it.ch> Fri Aug 02 14:16:14 2024 +0200
tree 1d4aa13913722a778af2a7a5334af7e05555ecca
parent e939c28a325766007b99e7dde295e50522781c17

Initial structure for aphy.guide

Adds the structure and some contents, most of them still WIP

src/.gitignore

diff --git a/src/.gitignore b/src/.gitignore
index b2d6de3..dfd8bf4 100644
--- a/src/.gitignore
+++ b/src/.gitignore
@@ -18,3 +18,5 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+*.swp

src/blog/2019-05-28-first-blog-post.md

diff --git a/src/blog/2019-05-28-first-blog-post.md b/src/blog/2019-05-28-first-blog-post.md
deleted file mode 100644
index 02f3f81..0000000
--- a/src/blog/2019-05-28-first-blog-post.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-slug: first-blog-post
-title: First Blog Post
-authors:
-  name: Gao Wei
-  title: Docusaurus Core Team
-  url: https://github.com/wgao19
-  image_url: https://github.com/wgao19.png
-tags: [hola, docusaurus]
----
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

src/blog/2019-05-29-long-blog-post.md

diff --git a/src/blog/2019-05-29-long-blog-post.md b/src/blog/2019-05-29-long-blog-post.md
deleted file mode 100644
index 26ffb1b..0000000
--- a/src/blog/2019-05-29-long-blog-post.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-slug: long-blog-post
-title: Long Blog Post
-authors: endi
-tags: [hello, docusaurus]
----
-
-This is the summary of a very long blog post,
-
-Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
-
-<!--truncate-->
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

src/blog/2021-08-01-mdx-blog-post.mdx

diff --git a/src/blog/2021-08-01-mdx-blog-post.mdx b/src/blog/2021-08-01-mdx-blog-post.mdx
deleted file mode 100644
index c04ebe3..0000000
--- a/src/blog/2021-08-01-mdx-blog-post.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-slug: mdx-blog-post
-title: MDX Blog Post
-authors: [slorber]
-tags: [docusaurus]
----
-
-Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
-
-:::tip
-
-Use the power of React to create interactive blog posts.
-
-```js
-<button onClick={() => alert('button clicked!')}>Click me!</button>
-```
-
-<button onClick={() => alert('button clicked!')}>Click me!</button>
-
-:::

src/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg

diff --git a/src/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/src/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
deleted file mode 100644
index 11bda09..0000000
--- a/src/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg
+++ /dev/null
Binary files differ

src/blog/2021-08-26-welcome/index.md

diff --git a/src/blog/2021-08-26-welcome/index.md b/src/blog/2021-08-26-welcome/index.md
deleted file mode 100644
index 9455168..0000000
--- a/src/blog/2021-08-26-welcome/index.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-slug: welcome
-title: Welcome
-authors: [slorber, yangshun]
-tags: [facebook, hello, docusaurus]
----
-
-[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
-
-Simply add Markdown files (or folders) to the `blog` directory.
-
-Regular blog authors can be added to `authors.yml`.
-
-The blog post date can be extracted from filenames, such as:
-
-- `2019-05-30-welcome.md`
-- `2019-05-30-welcome/index.md`
-
-A blog post folder can be convenient to co-locate blog post images:
-
-![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
-
-The blog supports tags as well!
-
-**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.

src/blog/authors.yml

diff --git a/src/blog/authors.yml b/src/blog/authors.yml
deleted file mode 100644
index bcb2991..0000000
--- a/src/blog/authors.yml
+++ /dev/null
@@ -1,17 +0,0 @@
-endi:
-  name: Endilie Yacop Sucipto
-  title: Maintainer of Docusaurus
-  url: https://github.com/endiliey
-  image_url: https://github.com/endiliey.png
-
-yangshun:
-  name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
-  image_url: https://github.com/yangshun.png
-
-slorber:
-  name: Sébastien Lorber
-  title: Docusaurus maintainer
-  url: https://sebastienlorber.com
-  image_url: https://github.com/slorber.png

src/blog/tags.yml

diff --git a/src/blog/tags.yml b/src/blog/tags.yml
deleted file mode 100644
index f71dd73..0000000
--- a/src/blog/tags.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-facebook:
-  label: Facebook
-  permalink: /facebook
-  description: Facebook tag description
-hello:
-  label: Hello
-  permalink: /hello
-  description: Hello tag description
-docusaurus:
-  label: Docusaurus
-  permalink: /docusaurus
-  description: Docusaurus tag description
-hola:
-  label: Hola
-  permalink: /hola
-  description: Hola tag description

src/docs/about-us.md

diff --git a/src/docs/about-us.md b/src/docs/about-us.md
new file mode 100644
index 0000000..8274ab2
--- /dev/null
+++ b/src/docs/about-us.md
@@ -0,0 +1,3 @@
+# About Us
+
+Company information

src/docs/about.md

diff --git a/src/docs/about.md b/src/docs/about.md
new file mode 100644
index 0000000..40c44af
--- /dev/null
+++ b/src/docs/about.md
@@ -0,0 +1,12 @@
+# What is Apostrophy?
+
+In a nutshell, Apostrophy is an Android-based operating system, a bunch of system services, and a
+number of software packages.
+
+But you knew that already. What is it really?
+
+Apostrophy integrates Android to mobile devices that are a part of a larger eco-system, and provides
+its customers with a turn-key solutions to in-house and on-prem some, many or all of the required
+processes.
+
+It's on a mission to fix the eco-system in mobility.

src/docs/developers/apps.md

diff --git a/src/docs/developers/apps.md b/src/docs/developers/apps.md
new file mode 100644
index 0000000..5246fa1
--- /dev/null
+++ b/src/docs/developers/apps.md
@@ -0,0 +1,7 @@
+# Applications
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/apps/application-development.md

diff --git a/src/docs/developers/apps/application-development.md b/src/docs/developers/apps/application-development.md
new file mode 100644
index 0000000..6305a0d
--- /dev/null
+++ b/src/docs/developers/apps/application-development.md
@@ -0,0 +1,5 @@
+# Application Development
+
+This category concerns independent application development.
+
+There is a separate section on [System Application Development](../platform/system-app-development).

src/docs/developers/apps/source-code-management.md

diff --git a/src/docs/developers/apps/source-code-management.md b/src/docs/developers/apps/source-code-management.md
new file mode 100644
index 0000000..32a127e
--- /dev/null
+++ b/src/docs/developers/apps/source-code-management.md
@@ -0,0 +1 @@
+# Source Code Management

src/docs/developers/documentation.md

diff --git a/src/docs/developers/documentation.md b/src/docs/developers/documentation.md
new file mode 100644
index 0000000..87c1c91
--- /dev/null
+++ b/src/docs/developers/documentation.md
@@ -0,0 +1,38 @@
+# Documentation
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+In general the documentation available through [Aphy Guide](https://aphy.guide) includes developer
+and user documentation, in the English language, in [Markdown](https://markdownguide.org) (through
+[Docusaurus](https://docusaurus.io/docs/)).
+
+## General Guidance
+
+    * line length is at maximum 100 (inclusive, exceptions are permitted)
+    * indentation is 4 spaces to an indentation level
+    * indentation is to be used for lists (such as this one)
+    * (... TBD ...)
+
+Since there is no specific admonition for TODO items, they are noted as illustrated in the following
+code-block;
+
+```
+:::note[TODO]
+
+your text here
+
+:::
+```
+
+which renders as
+
+:::note[TODO]
+
+your text here
+
+:::
+

src/docs/developers/intro.md

diff --git a/src/docs/developers/intro.md b/src/docs/developers/intro.md
new file mode 100644
index 0000000..82cff51
--- /dev/null
+++ b/src/docs/developers/intro.md
@@ -0,0 +1,7 @@
+# Development Introduction
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform.md

diff --git a/src/docs/developers/platform.md b/src/docs/developers/platform.md
new file mode 100644
index 0000000..fff8486
--- /dev/null
+++ b/src/docs/developers/platform.md
@@ -0,0 +1,64 @@
+# Android Platform Engineering
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy develops and maintains its operating system against a mixture of the following upstream
+organizations and projects:
+
+  * the Android Open Source Project (*AOSP*)
+  * Original Device Manufacturer (*ODM*) Board Support Packages (*BSP*)
+  * Independent Development Houses (*IDH*)
+  * Original Equipment Manufacturer (*OEM*) Software
+  * GrapheneOS (*Graphene*)
+  * various third-party Free Software packages
+  * in-house platform and software projects
+
+The ODM, IDH and their BSP are largely considered one set of packages colloquially referred to as
+"the BSP".
+
+## Mobile Device Requirements
+
+How many devices does each of the development community need?
+
+### Platform Engineers
+
+This is an overview of the number of devices needed by platform developers.
+
+| No. | Purpose                                                                                    |
+| --- | ------------------------------------------------------------------------------------------ |
+|   1 | Daily driver for personal use (production)                                                 |
+|   2 | Customer support (production) for the reproduction of customer issues                      |
+|   3 | Customer support (next), for validation testing of upcoming releases                       |
+| .n. | *n* devices for the purposes of topic development and validation testing                   |
+
+### System Package Development
+
+Most sytem packages can be developed independent from platform engineering, such that a build could
+be created without the system package included, and the package in development could then be side-
+loaded.
+
+Notable exceptions include [Aphy Launcher](./platform/system-packages/aphy-launcher),
+[Aphy Setup Wizard](./platform/system-packages/aphy-setupwizard), and more.
+
+As such, system package developers may only need 2 devices;
+
+| No. | Purpose                                                                                    |
+| --- | ------------------------------------------------------------------------------------------ |
+|   1 | Daily driver for personal use (production)                                                 |
+|   2 | System package development                                                                 |
+
+### Customer Support
+
+This is an overview of the number of devices needed by support personnel. While some are optional,
+they can also be temporarily repurposed for things like demonstration, documentation, etc.
+
+| No. | Purpose                                                                                    |
+| --- | ------------------------------------------------------------------------------------------ |
+|   1 | Daily driver for personal use (production)                                                 |
+|   2 | Customer support (production) for the reproduction of customer issues                      |
+|   3 | Customer support (next), for validation testing of upcoming releases                       |
+|   4 | Quality Assurance (development/experimental) for acceptance testing and quality assurance) |

src/docs/developers/platform/customizing-builds.md

diff --git a/src/docs/developers/platform/customizing-builds.md b/src/docs/developers/platform/customizing-builds.md
new file mode 100644
index 0000000..095f38f
--- /dev/null
+++ b/src/docs/developers/platform/customizing-builds.md
@@ -0,0 +1,7 @@
+# Customizing Builds
+
+:::note[TODO]
+
+This article is a work in progress
+
+:::

src/docs/developers/platform/development-process.md

diff --git a/src/docs/developers/platform/development-process.md b/src/docs/developers/platform/development-process.md
new file mode 100644
index 0000000..be112e4
--- /dev/null
+++ b/src/docs/developers/platform/development-process.md
@@ -0,0 +1,164 @@
+# Development Process
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Development starts with the creation of a ticket, describing the issue and solution space. Once work
+on this ticket starts, we expect to see the following artifacts;
+
+* a topic development branch for the relevant `platform_manifest` repository,
+
+* one topic development branch per repository impacted,
+
+* a topic with any patches submitted for review in Gerrit.
+
+The goal of this article is to outline how developers should work together, on functionality that
+Apostrophy OS implements, how it is tracked, reviewed, tested, implemented and applied and
+re-applied moving forward (onto moving and future releases of Android, as well as alternative
+builds).
+
+Ideally, we have;
+
+*   self-contained patches against one or more repositories (i.e. one per repository),
+
+*   that are recognizable in and by themselves (i.e. ticket numbers in their names), and
+
+*   that can be applied, or re-applied, or omitted individually (as sets), independently from other
+    (sets of) patches.
+
+## Choose a Strategy
+
+Our manifests do not lock in repositories to particular revisions, but instead follow HEAD for
+branches. This implies that for the duration of a topic being under development, the repositories
+unrelated to the topic being developed, and have thus not been forked off, can (and will) move
+forward.
+
+Acknowledging that topic development can not chase moving targets, it is recommended to consider
+following a particular strategy;
+
+### Branching off Individual Repositories
+
+Consider using a strategy branching off individual repositories as you go, taking in to account;
+
+  * Not too many repositories are impacted, or impact the topic at hand should they change.
+  * The development probably doesn't take a significant period of time.
+
+### Choosing a Global Branch-off Point
+
+For longer-running development projects and/or rich dependency trees, consider choosing a global
+branch-off point;
+
+  * Chooses a stable release tagged in all repositories, or tags all repositories to mark the
+    branch-off point.
+
+  * Executes topic development from said branch-off points, and makes merging or rebasing an
+    exercise for the later "review" stage of the process.
+
+## Branch, Code, Commit & Submit
+
+The process of coding in changes is a natural process, and of course you don't really want to commit
+and submit for review, a sloppy work-in-progress series of commits (that include superfluous log
+messages, maybe some logical mistakes, summary skill issues, etc.).
+
+### Step 1: Branch off Individual Repositories
+
+We start work by branching off a repository:
+
+```bash
+$ repo start <topic-branch-name> <path/to/repository/>
+```
+
+meaning, for example ticket T1785 (*Re-implement Ledger functionality*);
+
+```bash
+$ repo start dev/T1785 aphy/aos/
+```
+
+:::note[This is not the only repository that is going to need to be forked]
+:::
+
+Now, we edit `aphy/aos/aos.mk` and eject the `PRODUCT_PACKAGES += AphyLauncher` and associated
+lines, and remove associated artifacts. Commit it, push it;
+
+```bash
+# git -C aphy/aos/ push <remote> HEAD:refs/heads/<topic-branch-name>
+$ git -C aphy/aos/ push mc02 HEAD:refs/heads/dev/T1785
+```
+
+:::note[Force Pushes are (should be) permitted for `dev/` branches]
+:::
+
+The effective change here is that the inclusion of AphyLauncher no longer overrides the inclusion of
+`packages/apps/Launcher3` (if that just so happened to be already there, otherwise see Step 3).
+
+### Step 2: A New Repository?
+
+Considering we are forking a `graphene/` repository, we should establish an `aphy/` repository. But
+creating such repository is a privileged action, and can not be performed by individual developers.
+
+It is addressed during the review stage of the development process. For now, we can just make a
+mental note about it.
+
+### Step 3: Change the Platform Manifest
+
+In order to allow your colleagues and fellow enthusiasts to participate in the endeavour, provide
+them with a topic development version of the platform manifest.
+
+```bash
+$ cd $APHY_ROOT/src/aphyos/aphy/platform_manifest
+$ git checkout -b dev/T1785
+# Edit default.xml to reflect the new source locations and branches for the packages impacted
+$ git commit default.xml -m "dev/T1785"
+$ git push origin dev/T1785
+```
+
+### Step 4: Synchronize Release Build Hierarchy
+
+```bash
+$ cd $APHY_ROOT/build/
+$ repo init -u ssh://gerrit.aphy.ag/mc02/platform_manifest -b dev/T1785
+$ repo sync -j8
+```
+
+For internal system packages, you can edit source code in your build hierarchy directly, build and
+test the changes.
+
+For external system packages,
+
+### Step 5: Code, Share, Review, Release
+
+Do your work in isolation, or as part of a team, where your work is integrated and shared with
+colleagues for testing and feedback, through the aforementioned topic development branches and
+repository manifest changes. It is easy, cheap and essential.
+
+The Review stage is a submission of your topic development work to topic development branches in
+the related source code repositories (we address the constraints of needing sudden forks while
+working separately).
+
+## External System Packages
+
+This section concerns the system packages that are built external to the release build process,
+meaning the source code hierarchy for the system package lives outside of the release build
+hierarchies, and the release build hierarchy includes one or more APK files.
+
+We would seek to include either one of two system package build variants, namely the `release` APK
+for the **user** release build variant, and the `debug` APK for the **userdebug** release build
+variant, with something similar to the snippet shown here;
+
+```makefile
+(...)
+ifneq ($(filter $(TARGET_BUILD_VARIANT),eng userdebug),)
+LOCAL_SRC_FILES := $(LOCAL_MODULE)-userdebug.apk
+else
+LOCAL_SRC_FILES := $(LOCAL_MODULE)-user.apk
+endif
+(...)
+```
+
+## Internal System Packages
+
+Certain system packages are built internally to the release build process, in order to resolve
+accesses to privileged APIs, and/or be signed with `platform` keys.

src/docs/developers/platform/getting-started.md

diff --git a/src/docs/developers/platform/getting-started.md b/src/docs/developers/platform/getting-started.md
new file mode 100644
index 0000000..3c9c984
--- /dev/null
+++ b/src/docs/developers/platform/getting-started.md
@@ -0,0 +1,85 @@
+# Getting Started
+
+This is a quick guide to getting started with the source codes of Apostrophy OS.
+
+:::info[Not For Everyone]
+
+Many of the source code repositories require proper authorization. This excludes some 8 billion
+people, give or take a dozen.
+
+We are in the process of addressing what come-and-gone contributors' work looks like once published,
+and repositories will therefore be trickling in over time.
+
+:::
+
+## Step 1: Where?
+
+Please consider choosing a root for source code and build hierarchies, such as the example
+below, so that you may be able to work with multiple build hierarchies in parallel. This
+increases disk space requirements, but allows for each to be built and rebuilt against its
+appropriate previous version.
+
+```bash title="Example root for source and build hierarchies"
+$ mkdir ~/devel/src/aphy/aphyos/
+$ cd ~/devel/src/aphy/aphyos/
+```
+
+While it doesn't really matter where exactly you put this `APHY_ROOT`, it should have more than
+enough disk space, and ideally also rather speedy disks.
+
+:::tip[We will continue to refer to `$APHY_ROOT`, so ...]
+
+... maybe include the following line in `~/.bashrc`:
+
+```bash
+export APHY_ROOT="$HOME/devel/src/aphy/aphyos/"
+```
+
+:::
+
+## Step 2: Synchronize Some Source Code
+
+```bash title="Example process for the mainstream source and build hierarchy"
+$ mkdir -p $APHY_ROOT/build/
+$ cd $APHY_ROOT/build/
+$ repo init -u ssh://gerrit.aphy.ag/aphy/platform_manifest -b master
+$ repo sync -j8
+```
+
+:::note[TODO]
+
+We have to work on;
+
+  * optimizing these initial clones and their footprint on disk, by using a maximum clone-depth of
+    probably 1, and
+
+  * anonymous cloning, and/or public registration.
+
+:::
+
+## Step 3: Your First Build
+
+Execute your first build. If you run in to trouble here, you may not have all the required system
+packages installed, or some more mysterious problem is causing troubles.
+
+The script by default removes any old `OUT_DIR=` and builds the variants **user** (in
+`OUT_DIR=./user/`) and **userdebug** (in `OUT_DIR=./userdebug/`).
+
+```bash title="This could take a while"
+$ ./build.sh
+```
+
+#### See Also
+
+* [Platform Build Process](./platform-build-process)
+
+## Step 4 - 2<sup>64-1</sup>: Lather, Rinse and Repeat
+
+Edit some code, launch another build, try again.
+
+:::note
+
+Subsequent builds are probably best be executed using the `--quick` parameter to `./build.sh`. Yes
+please.
+
+:::

src/docs/developers/platform/hardware-requirements.md

diff --git a/src/docs/developers/platform/hardware-requirements.md b/src/docs/developers/platform/hardware-requirements.md
new file mode 100644
index 0000000..89fb752
--- /dev/null
+++ b/src/docs/developers/platform/hardware-requirements.md
@@ -0,0 +1,28 @@
+# Hardware Requirements
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy OS is built on a system with the following specifications:
+
+| Hardware | Make/Model/Qty                         |
+| -------- | -------------------------------------- |
+| CPU      | AMD Threadripper Pro                   |
+| Memory   | 512 GB DDR4 3200Mhz RAM [^1]           |
+| Disk     | 4x 4TB Kingston NVMe                   |
+|          | 10x Western Digital 4TB Red Caviar     |
+| OS       | Fedora (current or current minus one)  |
+| Airco    | ecofort CoolAir 9+ (because AMD [^2])  |
+| UPS      | APC Pro 1600 S [^3]                    |
+
+The signing system is a different system, about which you could dream, or speculate, or care less.
+
+[^1]: It shouldn't really take *that* much, but the release engineer's favorite editor is *emacs*,
+    OK?
+
+[^2]: It's not just a meme.
+
+[^3]: Not even XFS on NVMe is fast enough to risk corrupting up to 16TB worth of small files.

src/docs/developers/platform/platform-build-process.md

diff --git a/src/docs/developers/platform/platform-build-process.md b/src/docs/developers/platform/platform-build-process.md
new file mode 100644
index 0000000..ce1b396
--- /dev/null
+++ b/src/docs/developers/platform/platform-build-process.md
@@ -0,0 +1,51 @@
+# Platform Build Process
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy uses a build script to build and merge the *system* and *vendor* parts of the platform.
+
+Its invocation is relatively straight-forward:
+
+```
+$ ./build.sh
+```
+
+The script automatically creates a Python 2 virtual environment (in `./venv`) should it be required.
+To skip this step, specify `--without-venv`.
+
+The build script separates the working hierarchies for build variants, such that you will get a
+`./user/` and a `./userdebug/` hierarchy where the builds actually happen.
+
+By default, the build script removes entire build hierarchies (the working hierarchies). To avoid
+doing so, such as for repeated builds, consider using `--quick` to preserve pre-existing compilation
+outcomes that, if they have not changed, do not require compiling again.
+
+## Build Numbers
+
+The exact build number to use is derived as follows:
+
+  * Check the latest commit date for all managed repositories [^1]
+  * Check if any of the managed repositories is dirty (uncommitted work)
+  * If any of the managed repositories is dirty, the build date is today
+  * If none of the managed repositories is dirty, the build date is the date of the last commit
+  * Using the now established build date, check the number of builds that have already happened
+    using any existing build log files (and increment their latest number by one).
+
+For multiple working areas, consider specifying `--log-dir path/to/log/directory/`, to avoid
+multiple varying builds with the exact same build version.
+
+[^1]: See `repo list`.
+
+## Build Variants
+
+## OTA Packages
+
+To specify a specific release for which an OTA package should be created, use:
+
+```
+$ ./build.sh --ota <VERSION>
+```

src/docs/developers/platform/release-management.md

diff --git a/src/docs/developers/platform/release-management.md b/src/docs/developers/platform/release-management.md
new file mode 100644
index 0000000..907e42a
--- /dev/null
+++ b/src/docs/developers/platform/release-management.md
@@ -0,0 +1,7 @@
+# Release Management
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/signing-keys.md

diff --git a/src/docs/developers/platform/signing-keys.md b/src/docs/developers/platform/signing-keys.md
new file mode 100644
index 0000000..d9b1359
--- /dev/null
+++ b/src/docs/developers/platform/signing-keys.md
@@ -0,0 +1,33 @@
+# Signing Keys
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Signing keys for the Apostrophy OS platform and its updates exist in precisely two places;
+
+  * an air-gapped workstation at Apostrophy Technology HQ,
+
+  * a bank vault.
+
+The process of releasing updates to the platform (and its system packages) is therefore relatively
+involved.
+
+## Signing Processes
+
+We distinguish the following categories of processes:
+
+  * Android Platform developers, including those for system apps
+
+    Developers must be able to repeatedly and reliably (...)
+
+  * Intermediate releases not intended for public consumption
+
+    These include builds for feature preview releases, proof-of-concept implementations and
+    acceptance testing, but must not be applicable to general public devices
+
+  * General Availability Releases
+
+    For both the platform and intermediate updates to associated system packages

src/docs/developers/platform/software-requirements.md

diff --git a/src/docs/developers/platform/software-requirements.md b/src/docs/developers/platform/software-requirements.md
new file mode 100644
index 0000000..9cdd975
--- /dev/null
+++ b/src/docs/developers/platform/software-requirements.md
@@ -0,0 +1,49 @@
+# Software Requirements
+
+The author of this documentation runs [Fedora](https://fedoraproject.org), so that is what this part
+of the documentation is based on.
+
+    * `@development-tools`
+    * `@fedora-packager`
+    * `binutils-aarch64-linux-gnu`
+    * `binutils-arm-linux-gnu`
+    * `binutils-x86_64-linux-gnu`
+    * `ccache`
+    * `java`
+    * `java-devel`
+    * `gcc-c++`
+    * `glibc.i686`
+    * `libstdc++.i686`
+    * `libxcrypt-compat`
+    * `ncurses-compat-libs-6.4`
+    * `openssl`
+    * `p7zip`
+    * `python2.7`
+    * `repo`
+    * `zlib.i686`
+    * `zlib-ng-compat.i686`
+
+To do this in one fell swoop:
+
+```bash title="One-liner"
+$ sudo dnf -y install \
+    @development-tools \
+    @fedora-packager \
+    binutils-aarch64-linux-gnu \
+    binutils-arm-linux-gnu \
+    binutils-x86_64-linux-gnu \
+    ccache \
+    java \
+    java-devel \
+    gcc-c++ \
+    glibc.i686 \
+    libstdc++.i686 \
+    libxcrypt-compat \
+    ncurses-compat-libs-6.4 \
+    openssl \
+    p7zip \
+    python2.7 \
+    repo \
+    zlib.i686 \
+    zlib-ng-compat.i686
+```

src/docs/developers/platform/source-code-management.md

diff --git a/src/docs/developers/platform/source-code-management.md b/src/docs/developers/platform/source-code-management.md
new file mode 100644
index 0000000..8b89ca0
--- /dev/null
+++ b/src/docs/developers/platform/source-code-management.md
@@ -0,0 +1,105 @@
+# Source Code Management
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Platform source code repositories are maintained exclusively in [Gerrit](https://gerrit.aphy.ag).
+
+We maintain a few distinct prefixes for repositories:
+
+  * `aosp/` for mirrored copies of upstream Android Open Source Project repositories [^1]
+
+  * `graphene/` for mirrored copies of the upstream GrapheneOS Project repositories [^1] [^2]
+
+  * `<hardware>/` prefixes for source codes from hardware manufacturers
+
+  * `<odm|idh>/` prefixes for Original Device Manufacturers and Independent Development Houses
+
+  * `<device>/` prefixes for any original work on the device, should such exist
+
+  * `aphy/` for in-house work
+
+[^1]: You may have experienced a 429 Too Many Requests response once or twice before. In mirroring,
+    we avoid those rate-limiting shenanigans.
+
+[^2]: Graphene upstream being hosted on GitHub poses authentication as well as rate limitation
+    barriers at times.
+
+## Repository Manifests
+
+Not unlike many AOSP and AOSP-based projects, we utilize the `repo` utility for the management of
+multiple repositories.
+
+[This section](./getting-started) is about the use of `repo init -u <url> -b <branch>`.
+
+By convention, "current" or "next" releases reside on branches named "master", where everything that
+has been or is about to be released lives. All other topic development lives in branches prefixed
+with `dev/<topic>`. Topic development branches should adhere to a ticket number.
+
+## Step 1: The Board Support Package
+
+The BSP comes in two parts, both based on the AOSP project, but does not provide commit history nor
+separation of repositories in to its constituent elements [^3]. One part is for the vendor firmware,
+and the other is the operating system.
+
+[^3]: Ironically, the ~50 GB tarballs unpack to directory hierarchies prefixed with `git-`.
+
+This means Apostrophy initially imports the BSP in to a source code management system, and tracks
+subsequent changes to it in one or more very large monolithic repositories.
+
+We then analyze each of the candidate constituent elements using AOSP upstream repositories, and
+compare source code. Typically, a single-release BSP package contains some ~700-800 copies to an
+older tag in the upstream repositories. These are removed from the BSP and instead incorporated
+from (our mirror of) AOSP upstream.
+
+These upstream AOSP repositories are mirrored to our Gerrit server with the prefix `aosp/`. Note
+that we push to branches such as `aosp-$x`, where $x represents the generation of Android (i.e. 12,
+13, 14, etc.), and include any tags.
+
+## Step 2: More Graphene Please
+
+Graphene maintains forks of a relatively manageable sub-set of all AOSP repositories, meaning
+Apostrophy can now dissect the BSP further -- examination of where Graphene supplies its version.
+
+Further repositories include Graphene original source code (such as the Camera application).
+
+Each of these upstream Graphene repositories are mirrored to our Gerrit server with the prefix
+`graphene/`. Note that we push the relevant Graphene branches to `graphene-$x`, include any
+`aosp-$x` branches, and push tags from both Graphene and AOSP to our mirror.
+
+Once the Graphene version of a repository is picked up (and successfully incorporated), we can
+eliminate our `aosp/` mirror.
+
+## Step 3: A few sprinkles of Aphy
+
+For any number of devices and product streams, Apostrophy patches existing software or adds software
+from repositories prefixed with `<hardware>/`, `<device>/` or `aphy/`.
+
+Some repositories that are otherwise "vanilla upstream" (i.e. AOSP or Graphene) require
+Aphy-specific modifications, which would be rebased again and again against vanilla upstream
+changes.
+
+## Step 4: Examine the Rest
+
+Somewhere in the development process of Apostrophy OS, the following measurement was taken.
+
+First, we examine the number of files tracked by the original BSP hierarchy:
+
+```bash
+$ git ls-files | wc -l
+1432080
+```
+
+While the development process is still ongoing, we continue to reduce the number of such files:
+
+```bash
+$ git ls-files | wc -l
+665263
+```
+
+## Step 5: Bug-fixes & Security Patches
+
+TODO.

src/docs/developers/platform/system-app-development.md

diff --git a/src/docs/developers/platform/system-app-development.md b/src/docs/developers/platform/system-app-development.md
new file mode 100644
index 0000000..e5ab9b1
--- /dev/null
+++ b/src/docs/developers/platform/system-app-development.md
@@ -0,0 +1,9 @@
+# System Application Development
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+This section concerns the development process of System Applications, aka. *preloads*.

src/docs/developers/platform/system-packages.md

diff --git a/src/docs/developers/platform/system-packages.md b/src/docs/developers/platform/system-packages.md
new file mode 100644
index 0000000..762ad56
--- /dev/null
+++ b/src/docs/developers/platform/system-packages.md
@@ -0,0 +1,41 @@
+# System Packages
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+System packages are the software packages pre-loaded on to the system, and are developed and
+maintained by AOSP, Graphene, Apostrophy or independent third parties.
+
+## AOSP System Packages
+
+TBD.
+
+## Graphene System Packages
+
+TBD.
+
+## Apostrophy System Packages
+
+Apostrophy specifically develops and maintains the following applications;
+
+  * [Aphy Account](./system-packages/aphy-account)
+
+    Basic sign-in, sign-out and configuration management of the Apostrophy account the device user
+    holds.
+
+  * [Aphy Apps](./system-packages/aphy-apps)
+
+    The channel through which Apostrophy makes available the updates to system packages.
+
+  * [Aphy Calendar](./system-packages/aphy-calendar)
+  * [Aphy Companion](./system-packages/aphy-companion)
+  * [Aphy Contacts](./system-packages/aphy-contacts)
+  * [Aphy Email](./system-packages/aphy-email)
+  * [Aphy GMS Wizard](./system-packages/aphy-gmswizard)
+  * [Aphy Launcher](./system-packages/aphy-launcher)
+  * [Aphy Tasks](./system-packages/aphy-tasks)
+  * [Aphy Setup Wizard](./system-packages/aphy-setupwizard)
+  * [Aphy Store](./system-packages/aphy-calendar)

src/docs/developers/platform/system-packages/aphy-account.md

diff --git a/src/docs/developers/platform/system-packages/aphy-account.md b/src/docs/developers/platform/system-packages/aphy-account.md
new file mode 100644
index 0000000..1e2017b
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-account.md
@@ -0,0 +1,7 @@
+# Aphy Account
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-apps.md

diff --git a/src/docs/developers/platform/system-packages/aphy-apps.md b/src/docs/developers/platform/system-packages/aphy-apps.md
new file mode 100644
index 0000000..34f14e0
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-apps.md
@@ -0,0 +1,13 @@
+# Aphy Apps
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+The Apps application is pre-loaded on to every device running Apostrophy OS.
+
+This system application is forked from [GrapheneOS](https://grapheneos.org). We shouldn't have
+needed to fork, but we have had our reasons. [Read more](../../roadmap/graphene.md) about forking
+and contributing back.

src/docs/developers/platform/system-packages/aphy-calendar.md

diff --git a/src/docs/developers/platform/system-packages/aphy-calendar.md b/src/docs/developers/platform/system-packages/aphy-calendar.md
new file mode 100644
index 0000000..1f4e361
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-calendar.md
@@ -0,0 +1,9 @@
+# Aphy Calendar
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy does not yet ship a custom calendaring implementation.

src/docs/developers/platform/system-packages/aphy-companion.md

diff --git a/src/docs/developers/platform/system-packages/aphy-companion.md b/src/docs/developers/platform/system-packages/aphy-companion.md
new file mode 100644
index 0000000..291d044
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-companion.md
@@ -0,0 +1,7 @@
+# Aphy Companion
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-contacts.md

diff --git a/src/docs/developers/platform/system-packages/aphy-contacts.md b/src/docs/developers/platform/system-packages/aphy-contacts.md
new file mode 100644
index 0000000..958002a
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-contacts.md
@@ -0,0 +1,11 @@
+# Aphy Contacts
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy does not yet ship a custom address book application.
+
+Rather, it ships [`GrapheneOS/platform_packages_apps_Contacts`](https://github.com/GrapheneOS/platform_packages_apps_Contacts).

src/docs/developers/platform/system-packages/aphy-email.md

diff --git a/src/docs/developers/platform/system-packages/aphy-email.md b/src/docs/developers/platform/system-packages/aphy-email.md
new file mode 100644
index 0000000..185dc4a
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-email.md
@@ -0,0 +1,7 @@
+# Aphy Email
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-gmswizard.md

diff --git a/src/docs/developers/platform/system-packages/aphy-gmswizard.md b/src/docs/developers/platform/system-packages/aphy-gmswizard.md
new file mode 100644
index 0000000..213c235
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-gmswizard.md
@@ -0,0 +1,7 @@
+# Aphy GMS Wizard
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-launcher.md

diff --git a/src/docs/developers/platform/system-packages/aphy-launcher.md b/src/docs/developers/platform/system-packages/aphy-launcher.md
new file mode 100644
index 0000000..5555ae5
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-launcher.md
@@ -0,0 +1,22 @@
+# Aphy Launcher
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+The Aphy launcher application comes in two distinct generations;
+
+    1. A stable fork of Mediatek's version of the AOSP launcher, quickstep edition.
+
+        :::note This edition is to be obsoleted.
+
+    1. A currently unstable fork of Graphene's version of the AOSP launcher, which is a work in
+        progress.
+
+Apostrophy modifies the launcher to achieve the following functionality;
+
+    * Domus & Piazza separation (see [user feature documentation](../../../users/features/domus-and-piazza))
+    * Privacy & Carbon Ledger shortcuts (see [user feature documentation](../../../users/features/privacy-and-carbon-ledger))
+        * also requires changes to platform_packages_modules_Permission

src/docs/developers/platform/system-packages/aphy-setupwizard.md

diff --git a/src/docs/developers/platform/system-packages/aphy-setupwizard.md b/src/docs/developers/platform/system-packages/aphy-setupwizard.md
new file mode 100644
index 0000000..4ba70ab
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-setupwizard.md
@@ -0,0 +1,7 @@
+# Aphy Setup Wizard
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-store.md

diff --git a/src/docs/developers/platform/system-packages/aphy-store.md b/src/docs/developers/platform/system-packages/aphy-store.md
new file mode 100644
index 0000000..0474bbd
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-store.md
@@ -0,0 +1,7 @@
+# Aphy Store
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/aphy-tasks.md

diff --git a/src/docs/developers/platform/system-packages/aphy-tasks.md b/src/docs/developers/platform/system-packages/aphy-tasks.md
new file mode 100644
index 0000000..696b768
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/aphy-tasks.md
@@ -0,0 +1,7 @@
+# Aphy Tasks
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::

src/docs/developers/platform/system-packages/digitalnomad.md

diff --git a/src/docs/developers/platform/system-packages/digitalnomad.md b/src/docs/developers/platform/system-packages/digitalnomad.md
new file mode 100644
index 0000000..04ecaa4
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/digitalnomad.md
@@ -0,0 +1,13 @@
+# Digital Nomad
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Application Functionality
+
+## Client-Server Communication Model
+
+## Known Limitations

src/docs/developers/platform/system-packages/vanadium.md

diff --git a/src/docs/developers/platform/system-packages/vanadium.md b/src/docs/developers/platform/system-packages/vanadium.md
new file mode 100644
index 0000000..ca66148
--- /dev/null
+++ b/src/docs/developers/platform/system-packages/vanadium.md
@@ -0,0 +1,12 @@
+# Vanadium
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Vanadium provides the system to render views using web technologies, and provides the default
+browser for Apostrophy OS.
+
+It is inherited from Graphene.

src/docs/developers/roadmap.md

diff --git a/src/docs/developers/roadmap.md b/src/docs/developers/roadmap.md
new file mode 100644
index 0000000..9c29316
--- /dev/null
+++ b/src/docs/developers/roadmap.md
@@ -0,0 +1,34 @@
+# Roadmap
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+This is a collection of speculative, high-level roadmap items Apostrophy seeks to achieve in the
+future.
+
+Roadmap items should exist of;
+
+    * one or more problem spaces,
+
+    * an elaboration on the context(s),
+
+    * contemplation of the desired result(s),
+
+    * solution proposals and validation steps (including solutions that turn out to be invalid).
+
+Admittedly, it's not a map, and you couldn't point to any road provided this not-a-map, but it's a
+roadmap nonetheless. Sorry about that.
+
+| Epic                             | Summary                                                                                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Emulator](./roadmap/emulator)   | Achieve the ability to run AphyOS in an emulator, in order to significantly speed up development in at least a sub-set of territories         |
+| [Testing Automation](./roadmap/testing-automation) | Avoid stacking up technical debt, and test the functionality Apostrophy requires from its own implementations               |
+| [Parental Control](./roadmap/parental-control)     | TBD                                                                                                                         |
+| [MDM](./roadmap/MDM)             | Extend Mobile Device Management capabilities in ways the standard Android API does not allow third-party vendors of MDM solutions to achieve. |
+| [OTA](./roadmap/OTA)             | TBD                                                                                                                                           |
+| [AGPS](./roadmap/AGPS)           | TBD                                                                                                                                           |
+| [SUPL](./roadmap/SUPL)           | TBD                                                                                                                                           |
+| [App Store](./roadmap/app-store) | TBD                                                                                                                                           |

src/docs/developers/roadmap/AGPS.md

diff --git a/src/docs/developers/roadmap/AGPS.md b/src/docs/developers/roadmap/AGPS.md
new file mode 100644
index 0000000..5bc6e8e
--- /dev/null
+++ b/src/docs/developers/roadmap/AGPS.md
@@ -0,0 +1,15 @@
+# Assisted GPS
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/MDM.md

diff --git a/src/docs/developers/roadmap/MDM.md b/src/docs/developers/roadmap/MDM.md
new file mode 100644
index 0000000..52c5077
--- /dev/null
+++ b/src/docs/developers/roadmap/MDM.md
@@ -0,0 +1,15 @@
+# Mobile Device Management
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/OTA.md

diff --git a/src/docs/developers/roadmap/OTA.md b/src/docs/developers/roadmap/OTA.md
new file mode 100644
index 0000000..0990d00
--- /dev/null
+++ b/src/docs/developers/roadmap/OTA.md
@@ -0,0 +1,15 @@
+# Over The Air Updates
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/PNS.md

diff --git a/src/docs/developers/roadmap/PNS.md b/src/docs/developers/roadmap/PNS.md
new file mode 100644
index 0000000..1d8877c
--- /dev/null
+++ b/src/docs/developers/roadmap/PNS.md
@@ -0,0 +1,15 @@
+# Push Notification Services
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/SUPL.md

diff --git a/src/docs/developers/roadmap/SUPL.md b/src/docs/developers/roadmap/SUPL.md
new file mode 100644
index 0000000..68fa9ca
--- /dev/null
+++ b/src/docs/developers/roadmap/SUPL.md
@@ -0,0 +1,15 @@
+# Secure User Plane Location
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/VPN.md

diff --git a/src/docs/developers/roadmap/VPN.md b/src/docs/developers/roadmap/VPN.md
new file mode 100644
index 0000000..3b71aec
--- /dev/null
+++ b/src/docs/developers/roadmap/VPN.md
@@ -0,0 +1,15 @@
+# Virtual Private Network
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/app-store.md

diff --git a/src/docs/developers/roadmap/app-store.md b/src/docs/developers/roadmap/app-store.md
new file mode 100644
index 0000000..b7bc1de
--- /dev/null
+++ b/src/docs/developers/roadmap/app-store.md
@@ -0,0 +1,15 @@
+# Application Store
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/emulator.md

diff --git a/src/docs/developers/roadmap/emulator.md b/src/docs/developers/roadmap/emulator.md
new file mode 100644
index 0000000..4689f18
--- /dev/null
+++ b/src/docs/developers/roadmap/emulator.md
@@ -0,0 +1,15 @@
+# Emulator
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/graphene.md

diff --git a/src/docs/developers/roadmap/graphene.md b/src/docs/developers/roadmap/graphene.md
new file mode 100644
index 0000000..465c540
--- /dev/null
+++ b/src/docs/developers/roadmap/graphene.md
@@ -0,0 +1,54 @@
+# Graphene Contributions
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+Within the smartphone industry, we basically operate with a duopoly -- it's Apple, or Google.
+
+Were we to distinguish hardware from software, we discover that no, we're still limited to
+operations within the same duopoly. Hardware manufacturers have gotten comfortable doing just enough
+to be
+
+This here thing clearly isn't about the half-or-so, give or take a dozen, that is Apple, so let's
+concentrate.
+
+A GMS-complient device has been engrained in to any corporations' value proposition for so long now,
+even the major players don't realize thei reliance on GMS certification is both existential, and
+dependent on their competitor's approval.
+
+within an eco-system of
+getting PCBAs
+The economical significance of an Android device becoming available through the Google hook-in
+eco-system
+
+The Google eco-system is pretty well tied-in to the blessing of a single party vendor -- Google.
+
+It is known as GMS-compliant, and there's no OEM or ODM/IDH that has not geared
+On more than one occassion, Google gets to establish what components or component functionality is
+available, through AOSP or its proprietary "GMS Certified Edition", to what device, and at what cost
+(or benefit).
+
+Not only are manufacturers not provided much of a choice, nor are consumers. With consumers now
+having forgotten how to ask for nice things [^2], This is a dependency
+hell [^2]
+
+## Context(s)
+
+Graphene is unquestionably the adonis [^1] of enhancing privacy and security from what is otherwise
+freely available open source software projects, making its enhancements available to any consumer.
+
+[^1]: originally a mortal, ultiamtely achieving immortality, established a timeless ideal of beauty
+
+Graphene achieves a number of enhancements relevant to security and privacy, while supporting none
+but one series of devices -- the Google Pixels to which AOSP is geared.
+
+It's prowess should be on display to more devices, thus consumers, but device manufacturers should.
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/parental-control.md

diff --git a/src/docs/developers/roadmap/parental-control.md b/src/docs/developers/roadmap/parental-control.md
new file mode 100644
index 0000000..86de19d
--- /dev/null
+++ b/src/docs/developers/roadmap/parental-control.md
@@ -0,0 +1,19 @@
+# Parental Control
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+* requires pop-up at first setup providing option to set up the device with parental controls?
+
+    * citation needed
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/roadmap/testing-automation.md

diff --git a/src/docs/developers/roadmap/testing-automation.md b/src/docs/developers/roadmap/testing-automation.md
new file mode 100644
index 0000000..5f15db2
--- /dev/null
+++ b/src/docs/developers/roadmap/testing-automation.md
@@ -0,0 +1,15 @@
+# Testing Automation
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Problem Space(s)
+
+## Context(s)
+
+## Elaboration(s)
+
+## Solution(s) & Validation(s)

src/docs/developers/services.md

diff --git a/src/docs/developers/services.md b/src/docs/developers/services.md
new file mode 100644
index 0000000..8298c44
--- /dev/null
+++ b/src/docs/developers/services.md
@@ -0,0 +1,44 @@
+# Services
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+## Required Services
+
+The required services for devices running Apostrophy OS include those that provide the device with;
+
+* Vendor and (Operating) System updates (i.e. OTA infrastructure)
+* System Package updates (i.e. Apps repository)
+* Connectivity Checking (incl. Captive Portal detection)
+* (... TBD ...)
+
+Apostrophy therefore develops and/or maintains the client-side application, and/or the configuration
+of the client-side software, and/or the server infrastructure required for the client application to
+function.
+
+## Optional Services
+
+Devices with Apostrophy OS are more likely than not to ship with integration in to other services,
+including collaborative productivity suites and privacy-, anonymity- and/or security-oriented
+solutions. Let's categorize them.
+
+| Service     | Classification   | Description / Rasion d'etre |
+| ----------- | ---------------- | -----------
+| Email       | Productivity     | General email functionality, most commonly `@aphy.io` [^1].
+| Calendaring | Productivity     | Synchronization of Calendars so that they can be used on BYO devices as well [^1].
+| Contacts    | Productivity     | Synchronization of Address Books so that they can be used on BYO devices as well [^1].
+| Software    | Usability        | Software repository infrastructure for the distribution of selected applications [^2].
+| Tasks       | Productivity     | Synchronization of Task lists so that they can be used on BYO devices as well [^1].
+| VPN         | Privacy/Security | Virtual Private Network management and infrastructure [^3].
+
+[^1]: Apostrophy's services are backed by the Free Software collaboration suite
+    [Kolab][https://kolab.org].
+
+[^2]: The current implementation of the *Aphy Store* is subject to a
+    [development roadmap](./roadmap/app-store) item.
+
+[^3]: The current implementation of the VPN client, management and server infrastructure is subject
+    to a [development roadmap](./roadmap/VPN) item.

src/docs/intro.md

diff --git a/src/docs/intro.md b/src/docs/intro.md
deleted file mode 100644
index 45e8604..0000000
--- a/src/docs/intro.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-sidebar_position: 1
----
-
-# Tutorial Intro
-
-Let's discover **Docusaurus in less than 5 minutes**.
-
-## Getting Started
-
-Get started by **creating a new site**.
-
-Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
-
-### What you'll need
-
-- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
-
-## Generate a new site
-
-Generate a new Docusaurus site using the **classic template**.
-
-The classic template will automatically be added to your project after you run the command:
-
-```bash
-npm init docusaurus@latest my-website classic
-```
-
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
-
-The command also installs all necessary dependencies you need to run Docusaurus.
-
-## Start your site
-
-Run the development server:
-
-```bash
-cd my-website
-npm run start
-```
-
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
-
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
-
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

src/docs/terms/BSP.md

diff --git a/src/docs/terms/BSP.md b/src/docs/terms/BSP.md
new file mode 100644
index 0000000..8999a5b
--- /dev/null
+++ b/src/docs/terms/BSP.md
@@ -0,0 +1,5 @@
+---
+id: terms-BSP
+title: Board Support Package
+hoverText: Board Support Package
+---

src/docs/tutorial-basics/_category_.json

diff --git a/src/docs/tutorial-basics/_category_.json b/src/docs/tutorial-basics/_category_.json
deleted file mode 100644
index 2e6db55..0000000
--- a/src/docs/tutorial-basics/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "label": "Tutorial - Basics",
-  "position": 2,
-  "link": {
-    "type": "generated-index",
-    "description": "5 minutes to learn the most important Docusaurus concepts."
-  }
-}

src/docs/tutorial-basics/congratulations.md

diff --git a/src/docs/tutorial-basics/congratulations.md b/src/docs/tutorial-basics/congratulations.md
deleted file mode 100644
index 04771a0..0000000
--- a/src/docs/tutorial-basics/congratulations.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-sidebar_position: 6
----
-
-# Congratulations!
-
-You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
-
-Docusaurus has **much more to offer**!
-
-Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
-
-Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
-
-## What's next?
-
-- Read the [official documentation](https://docusaurus.io/)
-- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
-- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
-- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
-- Add a [search bar](https://docusaurus.io/docs/search)
-- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
-- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)

src/docs/tutorial-basics/create-a-blog-post.md

diff --git a/src/docs/tutorial-basics/create-a-blog-post.md b/src/docs/tutorial-basics/create-a-blog-post.md
deleted file mode 100644
index 550ae17..0000000
--- a/src/docs/tutorial-basics/create-a-blog-post.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-sidebar_position: 3
----
-
-# Create a Blog Post
-
-Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
-
-## Create your first Post
-
-Create a file at `blog/2021-02-28-greetings.md`:
-
-```md title="blog/2021-02-28-greetings.md"
----
-slug: greetings
-title: Greetings!
-authors:
-  - name: Joel Marcey
-    title: Co-creator of Docusaurus 1
-    url: https://github.com/JoelMarcey
-    image_url: https://github.com/JoelMarcey.png
-  - name: Sébastien Lorber
-    title: Docusaurus maintainer
-    url: https://sebastienlorber.com
-    image_url: https://github.com/slorber.png
-tags: [greetings]
----
-
-Congratulations, you have made your first post!
-
-Feel free to play around and edit this post as much as you like.
-```
-
-A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

src/docs/tutorial-basics/create-a-document.md

diff --git a/src/docs/tutorial-basics/create-a-document.md b/src/docs/tutorial-basics/create-a-document.md
deleted file mode 100644
index c22fe29..0000000
--- a/src/docs/tutorial-basics/create-a-document.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-sidebar_position: 2
----
-
-# Create a Document
-
-Documents are **groups of pages** connected through:
-
-- a **sidebar**
-- **previous/next navigation**
-- **versioning**
-
-## Create your first Doc
-
-Create a Markdown file at `docs/hello.md`:
-
-```md title="docs/hello.md"
-# Hello
-
-This is my **first Docusaurus document**!
-```
-
-A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).
-
-## Configure the Sidebar
-
-Docusaurus automatically **creates a sidebar** from the `docs` folder.
-
-Add metadata to customize the sidebar label and position:
-
-```md title="docs/hello.md" {1-4}
----
-sidebar_label: 'Hi!'
-sidebar_position: 3
----
-
-# Hello
-
-This is my **first Docusaurus document**!
-```
-
-It is also possible to create your sidebar explicitly in `sidebars.js`:
-
-```js title="sidebars.js"
-export default {
-  tutorialSidebar: [
-    'intro',
-    // highlight-next-line
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-};
-```

src/docs/tutorial-basics/create-a-page.md

diff --git a/src/docs/tutorial-basics/create-a-page.md b/src/docs/tutorial-basics/create-a-page.md
deleted file mode 100644
index 20e2ac3..0000000
--- a/src/docs/tutorial-basics/create-a-page.md
+++ /dev/null
@@ -1,43 +0,0 @@
----
-sidebar_position: 1
----
-
-# Create a Page
-
-Add **Markdown or React** files to `src/pages` to create a **standalone page**:
-
-- `src/pages/index.js` → `localhost:3000/`
-- `src/pages/foo.md` → `localhost:3000/foo`
-- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
-
-## Create your first React Page
-
-Create a file at `src/pages/my-react-page.js`:
-
-```jsx title="src/pages/my-react-page.js"
-import React from 'react';
-import Layout from '@theme/Layout';
-
-export default function MyReactPage() {
-  return (
-    <Layout>
-      <h1>My React page</h1>
-      <p>This is a React page</p>
-    </Layout>
-  );
-}
-```
-
-A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).
-
-## Create your first Markdown Page
-
-Create a file at `src/pages/my-markdown-page.md`:
-
-```mdx title="src/pages/my-markdown-page.md"
-# My Markdown page
-
-This is a Markdown page
-```
-
-A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).

src/docs/tutorial-basics/deploy-your-site.md

diff --git a/src/docs/tutorial-basics/deploy-your-site.md b/src/docs/tutorial-basics/deploy-your-site.md
deleted file mode 100644
index 1c50ee0..0000000
--- a/src/docs/tutorial-basics/deploy-your-site.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-sidebar_position: 5
----
-
-# Deploy your site
-
-Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
-
-It builds your site as simple **static HTML, JavaScript and CSS files**.
-
-## Build your site
-
-Build your site **for production**:
-
-```bash
-npm run build
-```
-
-The static files are generated in the `build` folder.
-
-## Deploy your site
-
-Test your production build locally:
-
-```bash
-npm run serve
-```
-
-The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).
-
-You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).

src/docs/tutorial-basics/markdown-features.mdx

diff --git a/src/docs/tutorial-basics/markdown-features.mdx b/src/docs/tutorial-basics/markdown-features.mdx
deleted file mode 100644
index 35e0082..0000000
--- a/src/docs/tutorial-basics/markdown-features.mdx
+++ /dev/null
@@ -1,152 +0,0 @@
----
-sidebar_position: 4
----
-
-# Markdown Features
-
-Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
-
-## Front Matter
-
-Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
-
-```text title="my-doc.md"
-// highlight-start
----
-id: my-doc-id
-title: My document title
-description: My document description
-slug: /my-custom-url
----
-// highlight-end
-
-## Markdown heading
-
-Markdown text with [links](./hello.md)
-```
-
-## Links
-
-Regular Markdown links are supported, using url paths or relative file paths.
-
-```md
-Let's see how to [Create a page](/create-a-page).
-```
-
-```md
-Let's see how to [Create a page](./create-a-page.md).
-```
-
-**Result:** Let's see how to [Create a page](./create-a-page.md).
-
-## Images
-
-Regular Markdown images are supported.
-
-You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):
-
-```md
-![Docusaurus logo](/img/docusaurus.png)
-```
-
-![Docusaurus logo](/img/docusaurus.png)
-
-You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:
-
-```md
-![Docusaurus logo](./img/docusaurus.png)
-```
-
-## Code Blocks
-
-Markdown code blocks are supported with Syntax highlighting.
-
-````md
-```jsx title="src/components/HelloDocusaurus.js"
-function HelloDocusaurus() {
-  return <h1>Hello, Docusaurus!</h1>;
-}
-```
-````
-
-```jsx title="src/components/HelloDocusaurus.js"
-function HelloDocusaurus() {
-  return <h1>Hello, Docusaurus!</h1>;
-}
-```
-
-## Admonitions
-
-Docusaurus has a special syntax to create admonitions and callouts:
-
-```md
-:::tip My tip
-
-Use this awesome feature option
-
-:::
-
-:::danger Take care
-
-This action is dangerous
-
-:::
-```
-
-:::tip My tip
-
-Use this awesome feature option
-
-:::
-
-:::danger Take care
-
-This action is dangerous
-
-:::
-
-## MDX and React Components
-
-[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
-
-```jsx
-export const Highlight = ({children, color}) => (
-  <span
-    style={{
-      backgroundColor: color,
-      borderRadius: '20px',
-      color: '#fff',
-      padding: '10px',
-      cursor: 'pointer',
-    }}
-    onClick={() => {
-      alert(`You clicked the color ${color} with label ${children}`)
-    }}>
-    {children}
-  </span>
-);
-
-This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
-
-This is <Highlight color="#1877F2">Facebook blue</Highlight> !
-```
-
-export const Highlight = ({children, color}) => (
-  <span
-    style={{
-      backgroundColor: color,
-      borderRadius: '20px',
-      color: '#fff',
-      padding: '10px',
-      cursor: 'pointer',
-    }}
-    onClick={() => {
-      alert(`You clicked the color ${color} with label ${children}`);
-    }}>
-    {children}
-  </span>
-);
-
-This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
-
-This is <Highlight color="#1877F2">Facebook blue</Highlight> !

src/docs/tutorial-extras/_category_.json

diff --git a/src/docs/tutorial-extras/_category_.json b/src/docs/tutorial-extras/_category_.json
deleted file mode 100644
index a8ffcc1..0000000
--- a/src/docs/tutorial-extras/_category_.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "label": "Tutorial - Extras",
-  "position": 3,
-  "link": {
-    "type": "generated-index"
-  }
-}

src/docs/tutorial-extras/img/docsVersionDropdown.png

diff --git a/src/docs/tutorial-extras/img/docsVersionDropdown.png b/src/docs/tutorial-extras/img/docsVersionDropdown.png
deleted file mode 100644
index 97e4164..0000000
--- a/src/docs/tutorial-extras/img/docsVersionDropdown.png
+++ /dev/null
Binary files differ

src/docs/tutorial-extras/img/localeDropdown.png

diff --git a/src/docs/tutorial-extras/img/localeDropdown.png b/src/docs/tutorial-extras/img/localeDropdown.png
deleted file mode 100644
index e257edc..0000000
--- a/src/docs/tutorial-extras/img/localeDropdown.png
+++ /dev/null
Binary files differ

src/docs/tutorial-extras/manage-docs-versions.md

diff --git a/src/docs/tutorial-extras/manage-docs-versions.md b/src/docs/tutorial-extras/manage-docs-versions.md
deleted file mode 100644
index ccda0b9..0000000
--- a/src/docs/tutorial-extras/manage-docs-versions.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-sidebar_position: 1
----
-
-# Manage Docs Versions
-
-Docusaurus can manage multiple versions of your docs.
-
-## Create a docs version
-
-Release a version 1.0 of your project:
-
-```bash
-npm run docusaurus docs:version 1.0
-```
-
-The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
-
-Your docs now have 2 versions:
-
-- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
-- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**
-
-## Add a Version Dropdown
-
-To navigate seamlessly across versions, add a version dropdown.
-
-Modify the `docusaurus.config.js` file:
-
-```js title="docusaurus.config.js"
-export default {
-  themeConfig: {
-    navbar: {
-      items: [
-        // highlight-start
-        {
-          type: 'docsVersionDropdown',
-        },
-        // highlight-end
-      ],
-    },
-  },
-};
-```
-
-The docs version dropdown appears in your navbar:
-
-![Docs Version Dropdown](./img/docsVersionDropdown.png)
-
-## Update an existing version
-
-It is possible to edit versioned docs in their respective folder:
-
-- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
-- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`

src/docs/tutorial-extras/translate-your-site.md

diff --git a/src/docs/tutorial-extras/translate-your-site.md b/src/docs/tutorial-extras/translate-your-site.md
deleted file mode 100644
index b5a644a..0000000
--- a/src/docs/tutorial-extras/translate-your-site.md
+++ /dev/null
@@ -1,88 +0,0 @@
----
-sidebar_position: 2
----
-
-# Translate your site
-
-Let's translate `docs/intro.md` to French.
-
-## Configure i18n
-
-Modify `docusaurus.config.js` to add support for the `fr` locale:
-
-```js title="docusaurus.config.js"
-export default {
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en', 'fr'],
-  },
-};
-```
-
-## Translate a doc
-
-Copy the `docs/intro.md` file to the `i18n/fr` folder:
-
-```bash
-mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
-
-cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
-```
-
-Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.
-
-## Start your localized site
-
-Start your site on the French locale:
-
-```bash
-npm run start -- --locale fr
-```
-
-Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.
-
-:::caution
-
-In development, you can only use one locale at a time.
-
-:::
-
-## Add a Locale Dropdown
-
-To navigate seamlessly across languages, add a locale dropdown.
-
-Modify the `docusaurus.config.js` file:
-
-```js title="docusaurus.config.js"
-export default {
-  themeConfig: {
-    navbar: {
-      items: [
-        // highlight-start
-        {
-          type: 'localeDropdown',
-        },
-        // highlight-end
-      ],
-    },
-  },
-};
-```
-
-The locale dropdown now appears in your navbar:
-
-![Locale Dropdown](./img/localeDropdown.png)
-
-## Build your localized site
-
-Build your site for a specific locale:
-
-```bash
-npm run build -- --locale fr
-```
-
-Or build your site to include all the locales at once:
-
-```bash
-npm run build
-```

src/docs/users/bill-of-materials.md

diff --git a/src/docs/users/bill-of-materials.md b/src/docs/users/bill-of-materials.md
new file mode 100644
index 0000000..a7d4882
--- /dev/null
+++ b/src/docs/users/bill-of-materials.md
@@ -0,0 +1,9 @@
+# Bill of Materials
+
+The following articles contain a rather extensive list of materials being used for a version of
+AphyOS purposed for a device.
+
+| OEM | Model | Stream | Shared | Unique |
+| --- | ----- | ------ | ------ | ------ |
+| Punkt | MC02 | MC02 | [BoM](./bill-of-materials/punkt-mc02/shared) | [BoM](./bill-of-materials/punkt-mc02/mc02) |
+| | | CIRCLE | [BoM](./bill-of-materials/punkt-mc02/shared) | [BoM](./bill-of-materials/punkt-mc02/circle) |

src/docs/users/bill-of-materials/punkt-mc02/circle.md

diff --git a/src/docs/users/bill-of-materials/punkt-mc02/circle.md b/src/docs/users/bill-of-materials/punkt-mc02/circle.md
new file mode 100644
index 0000000..f03b72e
--- /dev/null
+++ b/src/docs/users/bill-of-materials/punkt-mc02/circle.md
@@ -0,0 +1 @@
+# Punkt MC02

src/docs/users/bill-of-materials/punkt-mc02/mc02.md

diff --git a/src/docs/users/bill-of-materials/punkt-mc02/mc02.md b/src/docs/users/bill-of-materials/punkt-mc02/mc02.md
new file mode 100644
index 0000000..f03b72e
--- /dev/null
+++ b/src/docs/users/bill-of-materials/punkt-mc02/mc02.md
@@ -0,0 +1 @@
+# Punkt MC02

src/docs/users/bill-of-materials/punkt-mc02/shared.md

diff --git a/src/docs/users/bill-of-materials/punkt-mc02/shared.md b/src/docs/users/bill-of-materials/punkt-mc02/shared.md
new file mode 100644
index 0000000..f03b72e
--- /dev/null
+++ b/src/docs/users/bill-of-materials/punkt-mc02/shared.md
@@ -0,0 +1 @@
+# Punkt MC02

src/docs/users/features.md

diff --git a/src/docs/users/features.md b/src/docs/users/features.md
new file mode 100644
index 0000000..ecf8c07
--- /dev/null
+++ b/src/docs/users/features.md
@@ -0,0 +1,7 @@
+# Features
+
+:::note[TODO]
+
+This article is a work in progress
+
+:::

src/docs/users/features/domus-and-piazza.md

diff --git a/src/docs/users/features/domus-and-piazza.md b/src/docs/users/features/domus-and-piazza.md
new file mode 100644
index 0000000..b1aef2a
--- /dev/null
+++ b/src/docs/users/features/domus-and-piazza.md
@@ -0,0 +1,7 @@
+# Domus & Piazza
+
+:::note[TODO]
+
+This article is a work in progress
+
+:::

src/docs/users/features/privacy-and-carbon-ledger.md

diff --git a/src/docs/users/features/privacy-and-carbon-ledger.md b/src/docs/users/features/privacy-and-carbon-ledger.md
new file mode 100644
index 0000000..93fe421
--- /dev/null
+++ b/src/docs/users/features/privacy-and-carbon-ledger.md
@@ -0,0 +1,7 @@
+# Privacy & Carbon Ledger
+
+:::note[TODO]
+
+This article is a work in progress
+
+:::

src/docs/users/intro.md

diff --git a/src/docs/users/intro.md b/src/docs/users/intro.md
new file mode 100644
index 0000000..f0a443f
--- /dev/null
+++ b/src/docs/users/intro.md
@@ -0,0 +1,10 @@
+# An Introduction to Apostrophy
+
+:::note[TODO]
+
+This article is a work in progress.
+
+:::
+
+Apostrophy is an eco-system of smartphone hardware, firmware, operating system and software
+applications, and the services typically associated with mobile phone use.

src/docs/users/opsec.md

diff --git a/src/docs/users/opsec.md b/src/docs/users/opsec.md
new file mode 100644
index 0000000..9b84f79
--- /dev/null
+++ b/src/docs/users/opsec.md
@@ -0,0 +1,23 @@
+# OPSEC for Users
+
+:::note[TODO]
+
+This entire section is a work in progress
+
+:::
+
+We are assuming that you are a member of the general public, even though perhaps you are not.
+
+This section can either express to you a new insight, a boring detail, or something simply not
+applicable.
+
+Normally, we'd start our consultancy engagements with establishing the threat model. But that's not
+where you are right now.
+
+This section entertains the publication of some generalically termed guidance on generically
+applicable DOs and DONTs for a user to consider in their use of a mobile device, assisted by the
+fact it's running AphyOS.
+
+Please consider doing this step by step, and read rationales, and make informed decisions.
+
+    * [Scramble PIN](./opsec/scramble-your-pin-pad)

src/docs/users/opsec/scramble-your-pin-pad

diff --git a/src/docs/users/opsec/scramble-your-pin-pad b/src/docs/users/opsec/scramble-your-pin-pad
new file mode 100644
index 0000000..fc6b89b
--- /dev/null
+++ b/src/docs/users/opsec/scramble-your-pin-pad
@@ -0,0 +1 @@
+# Scramble Your PIN Pad

src/docs/users/opsec/scramble-your-pin-pad.md

diff --git a/src/docs/users/opsec/scramble-your-pin-pad.md b/src/docs/users/opsec/scramble-your-pin-pad.md
new file mode 100644
index 0000000..81d344d
--- /dev/null
+++ b/src/docs/users/opsec/scramble-your-pin-pad.md
@@ -0,0 +1,26 @@
+# Scramble Your PIN Pad
+
+We suppose that your PIN is going to be as poor as `123456`, even though that's not how easily you
+would seek to get compromised. You may have chosen a direct family member's date of birth.
+
+This is not about any of that.
+
+There are a finite number of ways to solicit the information required;
+
+* compell you
+* stab at easy values
+* stab at values considered memorable
+*
+
+
+scenarios for someone looking over your shoulder;
+
+:::note[TODO]
+
+```
+IMAGES SIDE BY SIDE
+LEFT: 1->2->3->4->5->6 (with arroews)
+RIGHT: Scrambled PIN Pad version (with arrows)
+```
+
+:::

src/docusaurus.config.js

diff --git a/src/docusaurus.config.js b/src/docusaurus.config.js
index 7b8d5b1..3fd12f4 100644
--- a/src/docusaurus.config.js
+++ b/src/docusaurus.config.js
@@ -8,22 +8,17 @@
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'My Site',
-  tagline: 'Dinosaurs are cool',
+  title: 'Aphy Guides',
+  tagline: 'Apostrophy OS Documentation',
   favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
-  url: 'https://your-docusaurus-site.example.com',
+  url: 'https://aphy.guide',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
 
-  // GitHub pages deployment config.
-  // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'facebook', // Usually your GitHub org/user name.
-  projectName: 'docusaurus', // Usually your repo name.
-
-  onBrokenLinks: 'throw',
+  onBrokenLinks: 'warn',
   onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
@@ -41,17 +36,6 @@
       ({
         docs: {
           sidebarPath: './sidebars.js',
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
-        },
-        blog: {
-          showReadingTime: true,
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
-          editUrl:
-            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
           customCss: './src/css/custom.css',
@@ -66,7 +50,7 @@
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
       navbar: {
-        title: 'My Site',
+        title: 'Aphy Docs',
         logo: {
           alt: 'My Site Logo',
           src: 'img/logo.svg',
@@ -74,15 +58,15 @@
         items: [
           {
             type: 'docSidebar',
-            sidebarId: 'tutorialSidebar',
+            sidebarId: 'developerSidebar',
             position: 'left',
-            label: 'Tutorial',
+            label: 'Developers',
           },
-          {to: '/blog', label: 'Blog', position: 'left'},
           {
-            href: 'https://github.com/facebook/docusaurus',
-            label: 'GitHub',
-            position: 'right',
+            type: 'docSidebar',
+            sidebarId: 'userSidebar',
+            position: 'left',
+            label: 'Users',
           },
         ],
       },
@@ -90,50 +74,47 @@
         style: 'dark',
         links: [
           {
-            title: 'Docs',
+            title: 'Developers',
             items: [
               {
-                label: 'Tutorial',
-                to: '/docs/intro',
+                label: 'Platform',
+                to: '/docs/developers/platform',
+              },
+              {
+                label: 'Apps',
+                to: '/docs/developers/apps',
+              },
+              {
+                label: 'Services',
+                to: '/docs/developers/services',
               },
             ],
           },
           {
-            title: 'Community',
+            title: 'Users',
             items: [
-              {
-                label: 'Stack Overflow',
-                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
-              },
-              {
-                label: 'Discord',
-                href: 'https://discordapp.com/invite/docusaurus',
-              },
-              {
-                label: 'Twitter',
-                href: 'https://twitter.com/docusaurus',
-              },
             ],
           },
           {
-            title: 'More',
+            title: 'Company',
             items: [
               {
-                label: 'Blog',
-                to: '/blog',
+                label: 'Website',
+                href: 'https://www.apostrophy.ch',
               },
               {
-                label: 'GitHub',
-                href: 'https://github.com/facebook/docusaurus',
+                label: 'Subscription',
+                href: 'https://aphy.app',
               },
             ],
           },
         ],
-        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+        copyright: `Copyright © ${new Date().getFullYear()} Apheleia IT AG`,
       },
       prism: {
         theme: prismThemes.github,
         darkTheme: prismThemes.dracula,
+        additionalLanguages: ['bash', 'makefile'],
       },
     }),
 };

src/sidebars.js

diff --git a/src/sidebars.js b/src/sidebars.js
index 3327580..272b892 100644
--- a/src/sidebars.js
+++ b/src/sidebars.js
@@ -13,21 +13,101 @@
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+    developerSidebar: [
+        {
+            type: 'category',
+            label: 'Developers',
+            link: {
+                type: "generated-index",
+                title: "Developers",
+                slug: "/category/developers",
+            },
+            items: [
+                {
+                    type: 'category',
+                    label: 'Platform',
+                    link: {
+                        type: "doc",
+                        id: 'developers/platform'
+                    },
+                    items: [
+                        'developers/platform/source-code-management',
+                        'developers/platform/hardware-requirements',
+                        'developers/platform/system-app-development',
+                        {
+                            type: 'category',
+                            label: 'System Packages',
+                            link: {
+                                type: 'doc',
+                                id: 'developers/platform/system-packages'
+                            },
+                            items: [
+                                'developers/platform/system-packages/aphy-account',
+                                'developers/platform/system-packages/aphy-apps',
+                                'developers/platform/system-packages/aphy-calendar',
+                                'developers/platform/system-packages/aphy-companion',
+                                'developers/platform/system-packages/aphy-contacts',
+                                'developers/platform/system-packages/aphy-email',
+                                'developers/platform/system-packages/aphy-gmswizard',
+                                'developers/platform/system-packages/aphy-launcher',
+                                'developers/platform/system-packages/aphy-tasks',
+                                'developers/platform/system-packages/aphy-setupwizard',
+                                'developers/platform/system-packages/aphy-store',
+                                'developers/platform/system-packages/digitalnomad',
+                                'developers/platform/system-packages/vanadium',
+                            ]
+                        },
+                        'developers/platform/development-process',
+                        'developers/platform/release-management',
+                        'developers/platform/platform-build-process',
+                        'developers/platform/signing-keys',
+                        'developers/platform/customizing-builds',
+                    ],
+                },
+                {
+                    type: 'category',
+                    label: 'Apps',
+                    link: {
+                        type: "doc",
+                        id: 'developers/apps/application-development'
+                    },
+                    items: [
+                    ]
+                },
+                'developers/services',
+                'developers/roadmap',
+                'developers/documentation',
+            ],
+        },
+    ],
+    userSidebar: [
+        {
+            type: 'category',
+            label: 'Users',
+            link: {
+                type: "doc",
+                id: "users/intro",
+            },
+            items: [
+                'users/intro',
+                {
+                    type: 'category',
+                    label: 'Features',
+                    link: {
+                        type: "doc",
+                        id: 'users/features'
+                    },
+                    items: [
+                        'users/features/domus-and-piazza',
+                        'users/features/privacy-and-carbon-ledger',
+                    ],
+                },
+                'users/opsec',
+                'users/bill-of-materials',
 
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-   */
+            ],
+        },
+    ],
 };
 
 export default sidebars;

src/src/components/HomepageFeatures/index.js

diff --git a/src/src/components/HomepageFeatures/index.js b/src/src/components/HomepageFeatures/index.js
index acc7621..99e9eb5 100644
--- a/src/src/components/HomepageFeatures/index.js
+++ b/src/src/components/HomepageFeatures/index.js
@@ -4,32 +4,13 @@
 
 const FeatureList = [
   {
-    title: 'Easy to Use',
-    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
+    title: 'Work in Progress',
     description: (
       <>
-        Docusaurus was designed from the ground up to be easily installed and
-        used to get your website up and running quickly.
-      </>
-    ),
-  },
-  {
-    title: 'Focus on What Matters',
-    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
-    description: (
-      <>
-        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
-        ahead and move your docs into the <code>docs</code> directory.
-      </>
-    ),
-  },
-  {
-    title: 'Powered by React',
-    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
-    description: (
-      <>
-        Extend or customize your website layout by reusing React. Docusaurus can
-        be extended while reusing the same header and footer.
+        This documentation is a work in progress -- we barely have what we think is a reasonably
+        OK structure.
+        <p/>
+        We're focussing on the <a href="/docs/category/developers">developers</a> documentation.
       </>
     ),
   },
@@ -37,10 +18,7 @@
 
 function Feature({Svg, title, description}) {
   return (
-    <div className={clsx('col col--4')}>
-      <div className="text--center">
-        <Svg className={styles.featureSvg} role="img" />
-      </div>
+    <div className={clsx('col col--12')}>
       <div className="text--center padding-horiz--md">
         <Heading as="h3">{title}</Heading>
         <p>{description}</p>

src/src/pages/index.js

diff --git a/src/src/pages/index.js b/src/src/pages/index.js
index a8c61f2..d2484cd 100644
--- a/src/src/pages/index.js
+++ b/src/src/pages/index.js
@@ -16,13 +16,6 @@
           {siteConfig.title}
         </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
-        <div className={styles.buttons}>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs/intro">
-            Docusaurus Tutorial - 5min ⏱️
-          </Link>
-        </div>
       </div>
     </header>
   );

src/src/pages/markdown-page.md

diff --git a/src/src/pages/markdown-page.md b/src/src/pages/markdown-page.md
deleted file mode 100644
index 9756c5b..0000000
--- a/src/src/pages/markdown-page.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: Markdown page example
----
-
-# Markdown page example
-
-You don't need React to write simple standalone pages.