update docs

arkanum

@@ -2,6 +2,7 @@
 
 set -e
 
+# region usage
 function showHelp() {
   cat << HELP
   🧙 arkanum ✨🌌☄️💥 is used to install optional tools for developing in a
@@ -40,6 +41,7 @@ function showHelp() {
   Example 3: arkanum config disable-motd
 HELP
 }
+# endregion usage
 
 function disableMotd() {
   if [[ -e "$HOME/enable_motd" ]]; then

docs/.vitepress/sidebar.mjs

@@ -22,6 +22,8 @@ function getGuide() {
             { text: 'VSCode', link: 'components/vscode' },
           ],
         },
+        { text: 'Known Issues', link: 'known-issues' },
+        { text: 'FAQs', link: 'faq' },
       ],
     },
   ]

docs/guide/about.md

@@ -24,7 +24,7 @@ And most important:
 
 The Arkanum project started when I was challenged to work on multiple projects from different locations
 and devices. Setting up VSCode based *DEV* environments can be hard and takes a minute. Especially when
-you think about all the tools, extensions and setup you needed to work efficiently. On top of this,
+you think about all the tools, extensions and setup needed to work efficiently. On top of this,
 you also want to keep the environments up to date to avoid version problems.
 
 Another motivation was the fact that I needed to find a way reducing the time for onboarding, supporting, and debugging the environments from other teammates.
@@ -33,4 +33,4 @@ So I started searching for existing solutions. I didn't wan't to go the traditio
 a software solution. Luckily there was already a way to use VS Code remotely and I started working with [coder/code-server](https://github.com/coder/code-server)
 and [gitpod-io/openvscode-server](https://github.com/gitpod-io/openvscode-server).
 
-In late 2022 I started customizing and started the open source project `Arkanum`.
+In late 2022 I decided to customize these project and so I started `Arkanum` as open-source project.

docs/guide/components/arkanum-cli.md

@@ -2,6 +2,31 @@
 
 ## About
 
+The `arkanum` container image includes the `arkanum-cli` to manage the current instance and be able to install
+additional resources. To keep the base image as small as possible we decided not ot include all possible frameworks. This decision also helps to give the use the ability to manage the needed framework versions like for
+NodeJS or Golang.
+
+For now the arkanum-cli is made with a simple bash script. But this could change whenever the complexity increases
+significantly.
+
+## Usage
+
+To use the cli just open a terminal and call the `arkanum` command. We also added a bash-completion
+script for the cli.
+
+<<< @/../arkanum#usage{34-36 bash:line-numbers}
+
+The first thing you normally after starting your Arkanum instance is setting the git user and email:
+
+`arkanum git setup "foobar" "foobar@arkanum.dev"`
+
+Now you can simple add your needed tools and frameworks:
+
+```bash
+arkanum install golang
+arkanum install nodejs
+```
+
 ## Referenced Source Files
 
 ::: code-group
@@ -10,5 +35,4 @@
 <<< @/../arkanum{bash}
 
 <<< @/../arkanum-completion{bash}
-
 :::

docs/guide/faq.md

@@ -0,0 +1 @@
+# 🤔 FAQs

docs/guide/getting-started.md

@@ -11,7 +11,7 @@ You need any host with either
 
 ### 📦 Get the image
 
-You can download the image from the gitea embedded container registry: `gitea.ocram85.com/arkanum/arkanum` with these tags:
+You can download the image from Gitea's embedded container registry: `gitea.ocram85.com/arkanum/arkanum` with these tags:
 
 - `latest` - Is based on the lasted master branch commit.
 - `next` - Is a test build based on the pull request
@@ -129,13 +129,6 @@ arkanum git setup "my-name" "my-email"
 
 And that's it. Now you're ready use arkanum as your daily remote code editor. 😄
 
-## 📖 Content
+## 🖼️ Screenshots
 
-<p align="center">
-  <a href="https://gitea.ocram85.com/arkanum/arkanum/">
-    <img
-      src="https://gitea.ocram85.com/arkanum/arkanum/raw/branch/master/assets/screen1.png"
-      alt="Screenshot1"
-    >
-  </a>
-</p>
+![screen1](/screens/screen1.png 'Arkanum startpage')

docs/guide/known-issues.md

@@ -0,0 +1,19 @@
+# 💣 Known Issues + Limitations
+
+## 🐛 Starship.rs
+
+Starship detects workspaces as active python projects. It always appends the prompt
+fragment `via 🐍 (lsiopy)`. For now I disabled the python module in starship.
+
+## 🐛 Default extensions installation timing error
+
+If the automatic installation of the default extension fails, you can always retry he installation with the
+following command:
+
+```bash
+# restart the installation
+arkanum config install-extensions
+# Optional: reset the vscode user setting
+arkanum config reset-codesettings
+# Reload with command F1 + Developer: Reload Window
+```