chore: restructure documentation (#6)

* chore: restructure documentation

* feat: enable github edit links for docs

* chore: update home page

* feat: teaser getting started article

docs/astro.config.mjs

@@ -14,6 +14,9 @@ export default defineConfig({
         dark: './src/assets/logo dark.svg',
         light: './src/assets/logo light.svg',
       },
+      editLink: {
+        baseUrl: 'https://github.com/kibu-sh/kibu/edit/main/docs',
+      },
       social: {
         github: 'https://github.com/kibu-sh/kibu',
         youtube: 'https://www.youtube.com/@kibu-sh',

docs/src/content/docs/guides/000 getting started.mdx

@@ -0,0 +1,119 @@
+---
+title: Getting Started
+description: Quickly get started with Kibu
+slug: guides/getting-started
+sidebar:
+    order: 0
+    label: Getting Started
+---
+import { Steps } from '@astrojs/starlight/components';
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip" title="Kibu is in Alpha">
+  Discern has been using Kibu since 2022.
+  We're excited to share this with the community.
+
+  Please keep in mind that we are actively porting this code from a closed source repo.
+  Part of this project is implementing new features that we want for ourselves and are excited to build with the community.
+
+  Until we reach a public 1.0 release, these guides may change in backwards incompatible ways.
+</Aside>
+
+# I want to skip the tutorial
+If you're eager to see the outcome of this tutorial,
+jump straight to our [templates' repo](https://github.com/kibu-sh/templates).
+
+
+# Starting from scratch
+<Steps>
+
+1. Start a new go project
+
+   ```shell
+   mkdir example
+   cd example
+   go mod init example
+   ```
+
+2. Install kibu's base tool chain
+
+    ```shell
+    go install github.com/google/wire/cmd/wire@latest
+    go install github.com/kibu-sh/kibu/internal/toolchain/kibugenv2/cmd/kibugenv2@main
+    go install github.com/kibu-sh/kibu/internal/toolchain/kibuwire/cmd/kibuwire@main
+    ```
+
+3. Jump start the project structure
+    ```shell
+    # this will be our code generation entrypoint
+    touch generate.go
+
+    # we need a place to put our first service
+    mkdir -p src/backend/systems/health/services
+    touch src/backend/systems/health/health.go
+    ```
+</Steps>
+
+
+## Let's write a simple service interface in Kibu
+
+`src/backend/systems/health/health.go`
+
+```go
+package health
+
+import (
+	"context"
+)
+
+type CheckRequest struct {}
+
+type CheckResponse struct {
+  Message string `json:"message"`
+}
+
+// Activities stub until bug is fixed
+//kibu:activity
+type Activities interface{}
+
+// Service checks the health of the entire system
+//
+//kibu:service
+type Service interface {
+  // Check returns a message letting us know the service is alive
+  //
+  //kibu:service:method method=GET
+  Check(ctx context.Context, req CheckRequest) (res CheckResponse, err error)
+}
+```
+
+## Now, generate some plumbing
+
+`generate.go`
+```go
+package generate
+
+// analyze each module and generate system plumbing code
+//go:generate kibugenv2 ./...
+
+// execute a second pass to generate wire superset
+//go:generate kibuwire ./...
+```
+
+```shell
+go generate generate.go
+```
+
+Two new files have manifested
+System plumbing for the interfaces we defined.
+`src/backend/systems/health/health.gen.go`
+
+A managed wire superset of all the `//kibu:provider` directives in the system.
+At scale, kibu makes managing wire sets a breeze across hundreds of services.
+`kibuwire/kibuwire.gen.go`
+
+
+<Aside type="note" title="Stay Tuned">
+  We will be pushing updates to these docs and tutorials daily.
+  Keep up over on our [Discord](https://discord.gg/5sga863FVB) to stay up to date.
+</Aside>

docs/src/content/docs/guides/001 project structure.mdx

@@ -0,0 +1,33 @@
+---
+title: Project Structure
+description: TODO
+---
+import { FileTree } from '@astrojs/starlight/components';
+
+This is our recommended project structure.
+While kibu doesn't enforce this specific structure, we recommend this for long term maintainability.
+
+<FileTree>
+  - docker-compose.core.yaml
+  - docker-compose.yaml
+  - go.mod
+  - go.sum
+  - kibu.go
+  - src/
+    - backend/
+      - cmd/
+        - server/ this is where your main.go lives
+      - database/
+        - migrations/
+        - models/
+        - queries/
+      - systems/
+        - billingv1/
+          - **billingv1.go** your interfaces go here
+          - activities/ implementations go in these subdirectories
+          - services/
+          - workflows/
+        - ... many more systems
+      - gen/
+        - kibuwire/ kibu generates a wire super set
+</FileTree>

docs/src/content/docs/guides/faq.md → docs/src/content/docs/guides/002 faq.md

@@ -1,6 +1,8 @@
 ---
 title: FAQ
 description: Frequently asked questions
+sidebar:
+    hidden: true
 ---
 
 Should I ignore generated files?

docs/src/content/docs/guides/Managing-Secrets-Configurations.md → docs/src/content/docs/guides/003 secrets and config.mdx

@@ -1,6 +1,8 @@
 ---
-title: Managing Secrets & Configurations
+title: Secrets & Configurations
 description: TODO
+sidebar:
+  hidden: true
 ---
 
 # Managing Secrets & Configurations

docs/src/content/docs/index.mdx

@@ -6,41 +6,44 @@ hero:
   title: |
     Welcome to
     <span
-      class="font-black text-transparent
-        bg-clip-text bg-gradient-to-b
-        from-accent-700 to-accent-400
-        dark:from-accent-500 dark:to-accent-200"
+      class="text-kibu-light"
     >
-      Kibu
+      Kibu (Alpha)
     </span>
   tagline: A developer productivity toolkit written in Go powered by Temporal
   image:
-    file: ../../assets/houston.webp
+    file: ../../assets/icon dark.svg
   actions:
     - text: Get Started
-      link: /guides/001_start
+      link: /guides/getting-started
       icon: right-arrow
     - text: Check out the source
       link: https://github.com/kibu-sh/kibu
       icon: external
       variant: minimal
 ---
 
-import { Card, CardGrid } from '@astrojs/starlight/components';
+import { Card, CardGrid } from '@astrojs/starlight/components'
 
-## Next steps
+## Build with developers in mind
 
 <CardGrid stagger>
-	<Card title="Update content" icon="pencil">
-		Edit `src/content/docs/index.mdx` to see this page change.
+	<Card title="Battle Tested" icon="seti:bicep">
+		Powerful open source technologies like [Temporal][tmpl], [Postgres][pg], and [Go][go].
+    Two years of production use at [Discern][disc] before OSS alpha.
 	</Card>
-	<Card title="Add new content" icon="add-document">
-		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	<Card title="Automate" icon="rocket">
+		Generate plumbing, live-reloading, stay focused, deploy faster!
 	</Card>
-	<Card title="Configure your site" icon="setting">
-		Edit your `sidebar` and other config in `astro.config.mjs`.
+	<Card title="Modular" icon="setting">
+		Use only what you need, or adopt a full stack way of building Go <apps className=""></apps>
 	</Card>
 	<Card title="Read the docs" icon="open-book">
-		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+		Learn more in [the Kibu Docs](/guides/getting-started).
 	</Card>
 </CardGrid>
+
+[tmpl]: https://temporal.io/
+[pg]: https://www.postgresql.org/
+[go]: https://go.dev/
+[disc]: https://discern.com/

docs/src/content/docs/reference/cli/000 kibu dev.md

@@ -0,0 +1,6 @@
+---
+title: kibu init
+description: TODO
+sidebar:
+    order: 0
+---

docs/src/content/docs/guides/encoding.md → docs/src/content/docs/reference/cli/001 kibu build.md

@@ -1,4 +1,4 @@
 ---
-title: Encoding
+title: kibu build
 description: TODO
 ---