Add tutorial, reference, and basic table of contents

app/docs/src/.vitepress/config.ts

@@ -6,7 +6,7 @@ dotenv.config();
 
 export default defineConfig({
   title: "System Initiative Docs",
-  description: "Description goes here",
+  description: "The documentation for System Initiative https://systeminit.com",
   markdown: {
     theme: {
       light: "github-light",

app/docs/src/changelog/roadmap.md

@@ -0,0 +1,3 @@
+# Roadmap
+
+...

app/docs/src/index.md

@@ -4,51 +4,64 @@ keywords:
   - docs
 ---
 
-# Welcome to System Initiative Documentation
+# System Initiative
 
-## Empowering Your Infrastructure Management
+System Initiative is a cloud application platform that makes it easier, safer,
+and faster to deploy applications, build infrastructure, and manage them over
+time.
 
-Welcome to the official documentation for System Initiative. Our platform is
-designed to revolutionize the way you manage and optimize your infrastructure,
-making it easier, more efficient, and more collaborative than ever before.
+<div class="tip custom-block" style="padding-top: 8px">
 
-### What is System Initiative?
+Just want to try it out? Skip to the [Quickstart](./tutorials/orientation.md).
 
-System Initiative is a cutting-edge platform that combines infrastructure as
-code, collaboration tools, and intelligent automation to streamline your DevOps
-processes. Our solution empowers teams to work together seamlessly, manage
-complex systems with ease, and accelerate development cycles.
+</div>
 
-### Key Features
+## Key Features
 
-- **Infrastructure as Code**: Define and manage your infrastructure using
-  familiar coding practices.
-- **Collaborative Workspace**: Work together in real-time with your team,
-  regardless of location.
-- **Intelligent Automation**: Leverage AI-driven insights to optimize your
-  infrastructure decisions.
-- **Version Control**: Keep track of changes and roll back when needed with
-  built-in versioning.
-- **Compliance and Security**: Ensure your infrastructure meets industry
-  standards and best practices.
+### Short Feedback Loops
+
+Every change is validated and qualified immediately. Reconciliation can happen
+individually or in batches, making application changes orders of magnitude
+faster.
+
+### High Intelligence
+
+Configuration can be inferred through the relationships between models. Changing
+a value at the source cascades throughout all the dependent models, making
+complex configuration easy to express. Code is automatically generated from the
+model.
+
+### Easy Collaboration
+
+Fully multiplayer coding and interactive diagrams make working together more
+like Figma and Notion, and less like GitHub. Everything is open source, with
+integrated open source module sharing.
+
+### Natural Context Windows
+
+The entire life cycle is built in to a single power tool. Customization happens
+in the application. New experiences are built around the data.
 
 ### Getting Started
 
 New to System Initiative? Here are some resources to help you get up and
 running:
 
-1. [Quick Start Guide](./quick-start.md)
-2. [Core Concepts](./core-concepts.md)
-3. [Installation](./installation.md)
-4. [Your First Project](./first-project.md)
+1. [Quick Start Guide](./tutorials/orientation.md)
+2. [Core Concepts](./reference/core-concepts.md)
 
 ### Need Help?
 
 If you have any questions or need assistance, our support team is here to help:
 
-- [FAQs](./faqs.md)
+[![Discord Server](https://img.shields.io/badge/discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/system-init)
+
+- [FAQ](./reference/faq.md)
 - [Community Forum](https://community.systeminit.com)
-- [Contact Support](mailto:[email protected])
+
+### Developing System Initaitive
+
+1. [Development Environment](./reference/dev/development-environment.md)
 
 Thank you for choosing System Initiative. Let's build amazing infrastructure
 together!

app/docs/src/reference/assset-builder.md

@@ -0,0 +1,3 @@
+# Asset Builder API
+
+Explanation of how the Asset Builder and associated API

app/docs/src/reference/core-concepts.md

@@ -0,0 +1,27 @@
+# Core Concepts
+
+## Full Fidelity Model
+
+A full fidelity model of the resources in your system - such as:
+
+- AWS
+- Docker
+- Kubernetes
+
+## Qualify the Model
+
+We then qualify the model to give real time feedback on its suitability Use
+relationships between models to infer configuration
+
+## Automatically Generate the Necessary Code
+
+Automatically generate necessary code
+
+## Fully programmable
+
+Fully programmable and customizable from within the application
+
+## Bi-directional reconciliation
+
+Bi-directional reconciliation of the simulation with the real system (and in the
+future, automatic creation of the simulation)

app/docs/src/reference/dev/development-environment.md

@@ -0,0 +1,204 @@
+# Development Environment
+
+Developing SI locally can be done in a variety of ways, but the officially
+supported method is to use the [`nix` flake](flake.nix) at the root of the
+repository.
+
+## Supported Platforms
+
+Using the flake requires using one of the below platforms. It is possible that
+the System Initiative software can be developed on even more platforms, but
+these platforms have been validated to work with `nix` and the corresponding
+flake.
+
+### macOS
+
+macOS (Darwin) is officially supported on both x86_64 (amd64) (also known as
+"Intel") and aarch64 (arm64) (also known as "Apple Silicon") architectures. We
+do not specify the minimum version of macOS that must be used, so we recommend
+looking at the "Dependencies" section for more information.
+
+For aarch64 (arm64) users, [Rosetta 2](https://support.apple.com/en-us/HT211861)
+must be installed. You can either install it via directions from the official
+support page or by running `softwareupdate --install-rosetta`.
+
+On macOS, you will likely hit the file descriptor limit, which requires user
+intervention. We have a section further down that describes how to intervene.
+
+### Linux
+
+Linux (GNU) is officially supported on both x86_64 (amd64) and aarch64 (arm64)
+architectures. [NixOS](https://nixos.org/) is not supported at this time, but
+may be desired in the future. Linux with MUSL instead of GNU is also not
+currently supported.
+
+In general, GNU-based distros that are roughly
+[FHS-compliant](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)
+will work. Those include, but are not limited to the following: Ubuntu, Fedora,
+Debian, Arch Linux, and openSUSE.
+
+### Windows
+
+Using native Windows is not supported at this time, but may be desired in the
+future. However, [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) on
+Windows 10 and Windows 11 is officially supported on both x86_64 (amd64) and
+aarch64 (arm64) architectures. In order to work with `nix`, `systemd` may need
+to be enabled in your WSL2 distro of choice.
+
+On WSL2, you will likely hit the file descriptor limit, which requires user
+intervention. We have a section further down that describes how to intervene.
+
+## Tuning the File Descriptor Limit
+
+On some systems, you may need to significantly increase the file descriptor
+limit for building and running our services with `buck2`. This is because
+`buck2` opens many more files than either `cargo` or `pnpm` do. Not only that,
+but when using Tilt to build and run concurrent services, even more files are
+opened than they would be for sequential builds.
+
+Increasing the file descriptor limit is possible via the `ulimit` command. To
+see all limits, execute the following command:
+
+```bash
+ulimit -a
+```
+
+Here is an example of a significant limit increase, where the argument provided
+after the flag represents the new desired number of file descriptors:
+
+```bash
+ulimit -n <file-descriptor-count>
+```
+
+To find an acceptable limit, run the health check command.
+
+```bash
+buck2 run dev:healthcheck
+```
+
+## Dependencies
+
+For all supported platforms, there are two dependencies that must be installed,
+`nix` (preferably via the
+[Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer))
+and `docker`.
+
+### Nix
+
+We use `nix` as our package manager for the repository. It ensures that our
+developers are all using the same versions of all packages and libraries for
+developing SI.
+
+Regardless of how `nix` is installed, it must have the
+[flakes](https://nixos.wiki/wiki/Flakes) feature enabled. We highly recommend
+using the
+[Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer)
+over the official installer; one reason being that the former will enable flakes
+by default.
+
+> [!TIP] You can use `direnv` (version >= 2.30) with our
+> [`nix` flake](flake.nix) for both ease of running commands and for editor
+> integration.
+>
+> For more information, see the **Direnv** section.
+
+### Docker
+
+We use `docker` to run our dependent services for the SI stack. It can either be
+installed via [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+or directly via [Docker Engine](https://docs.docker.com/engine/).
+
+For Docker Desktop, the version corresponding to your native architecture should
+be used (e.g. install the aarch64 (arm64) version on a Apple-Silicon-equipped
+MacBook Pro).
+
+WSL2 users should be able to use either Docker Desktop for WSL2 or Docker Engine
+(i.e. installing and using `docker` within the distro and not interacting with
+the host).
+
+Regardless of platform, you may need to configure credentials in
+`~/.local/share`.
+
+#### Rancher Desktop
+
+Since [Rancher Desktop](https://rancherdesktop.io/) provides the ability to use
+[moby](https://github.com/moby/moby), you can use it to run and develop the
+System Initiative software. However, it is untested, and you may need to further
+configuration depending on your platform.
+
+### (Optional) Direnv
+
+[Direnv](https://direnv.net/) (version >= 2.30) with
+[nix-direnv](https://github.com/nix-community/nix-direnv) can automatically set
+up your shell, which means you don't need to enter a subshell with
+`nix develop`, or prefix all commands with `nix develop --command`.
+
+You can install it with
+[your package manager of choice](https://direnv.net/docs/installation.html), but
+if you're unsure which installation method to use or your package manager does
+not provide a compatible version, you can use `nix` itself (e.g.
+`nix profile install nixpkgs#direnv`).
+
+We recommend using
+[the upstream docs for hooking `direnv` into your shell](https://direnv.net/docs/hook.html),
+but here is an example on how to do it on a system where `zsh` is the default
+shell. In this example, the following is added to the end of `~/.zshrc`.
+
+```zsh
+if [ $(command -v direnv) ]; then
+   eval "$(direnv hook zsh)"
+fi
+```
+
+There are also plugins to integrate `direnv` with common editors.
+
+#### Editor Plugin Support
+
+- Emacs: [emacs-direnv](https://github.com/wbolster/emacs-direnv)
+- IntelliJ-based IDEs:
+  [Direnv integration](https://plugins.jetbrains.com/plugin/15285-direnv-integration),
+  [Better Direnv](https://plugins.jetbrains.com/plugin/19275-better-direnv)
+- Neovim and Vim: [direnv.vim](https://github.com/direnv/direnv.vim)
+- Visual Studio Code:
+  [direnv](https://marketplace.visualstudio.com/items?itemName=mkhl.direnv)
+
+## How to Run Commands
+
+All commands need to be run from the `nix` environment. There are two primary
+options to do so:
+
+1. If `direnv` is installed _and_ hooked into your shell, you can `cd` into the
+   repository and `nix` will boostrap the environment for you using the flake.
+2. Otherwise, you can execute `nix develop` to enter the environment,
+   `nix develop --command <command>` to execute a command, or use the
+   environment in whatever way your prefer.
+
+## How Will I Know That Each Component Is Ready?
+
+For backend services like `veritech` and `sdf`, there will usually be an
+`INFO`-level log indicating that the webserver has bound to a port and is ready
+to receive messages. This may be subject to change (e.g. underlying library is
+upgraded to a new major version and the startup sequence changes) and will vary
+from component to component.
+
+# Troubleshooting
+
+This section contains common troubleshooting scenarios when working on the
+System Initiative software.
+
+## Build Errors Related to Running Services Reliant on `node_modules`
+
+Since we switched to `buck2` for our build infrastructure in mid-2023, you may
+experience issues when running services reliant on `node_modules` within older
+cloned instances of the repostiory. To solve these build errors, run the
+following in the root of your repository:
+
+> [!WARNING] > _This command deletes files._ Ensure your current working
+> directory is the root of the repository and understand what the command does
+> before executing. Please reach out to us
+> [on our Discord server](https://discord.com/invite/system-init) if you have
+> any questions.
+
+```bash
+find app bin lib third-party/node -type d -name node_modules -exec rm -rf {} \;; rm -rf node_modules
+```

app/docs/src/reference/faq.md

@@ -0,0 +1,19 @@
+# FAQ
+
+## Is it open source?
+
+## Isn't this just clickops?
+
+## Where is git?
+
+## Can I trigger this somehow?
+
+## How many clouds do you support?
+
+## Who do you compete with?
+
+## Replacing our automation will take forever
+
+## Can you deploy it on prem?
+
+## What's next?