@smbcloud / smbcloud-docs / commits / 36dbe57

Add Platform product docs and /developer section

Product documentation for smbCloud Platform plus a synced developer hub. Platform (main site): - home page reframed as "Four services. One platform." - one page per service: Deploy, Auth, Mail, GresIQ (SKILL.md voice) - sidebar grouped: Platform / Developer / More; About updated - rename site title to "smbCloud Platform Documentation" Developer (/developer): - scripts/sync-developer-docs.mjs (pnpm sync:developer) pulls docs/ from the smbcloud-cli repo (main branch) into content/developer/ and regenerates nav; synced pages link back to source. Excludes mail-service.md (scratch notes). - vendored 7 synced pages: CLI install (native/homebrew/npm/pypi) + contributing - hand-written overview pages for developer, developer/cli, developer/contributing - remove old content/cli (CLI now lives under /developer/cli) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Seto Elkahfi committed Jun 21, 2026 at 14:42 UTC 36dbe577896b612694ce4ec9254e743795c9b085
26 files changed +794 -49
app/layout.jsx
+9 -9
@@ -6,22 +6,22 @@ import 'nextra-theme-docs/style.css'
6 export const metadata = {
7 metadataBase: new URL('https://docs.smbcloud.xyz'),
8 title: {
9 - default: 'smbCloud Documentation',
10 - template: '%s – smbCloud Documentation'
9 + default: 'smbCloud Platform Documentation',
10 + template: '%s – smbCloud Platform Documentation'
11 },
12 - description: 'smbCloud Documentation',
13 - applicationName: 'smbCloud Documentation',
12 + description: 'smbCloud Platform Documentation',
13 + applicationName: 'smbCloud Platform Documentation',
14 openGraph: {
15 - title: 'smbCloud Documentation',
16 - description: 'smbCloud Documentation',
15 + title: 'smbCloud Platform Documentation',
16 + description: 'smbCloud Platform Documentation',
17 url: 'https://docs.smbcloud.xyz',
18 - siteName: 'smbCloud Documentation'
18 + siteName: 'smbCloud Platform Documentation'
19 }
20 }
21
22 const navbar = (
23 <Navbar
24 - logo={<span>smbCloud Documentation</span>}
24 + logo={<span>smbCloud Platform Documentation</span>}
25 projectLink="https://github.com/smbcloudXYZ"
26 />
27 )
@@ -30,7 +30,7 @@ const footer = (
30 <Footer>
31 MIT {new Date().getFullYear()} ©{' '}
32 <a href="https://docs.smbcloud.xyz" target="_blank" rel="noreferrer">
33 - smbCloud Documentation
33 + smbCloud Platform Documentation
34 </a>
35 </Footer>
36 )
content/_meta.js
+17 -1
@@ -1,5 +1,21 @@
1 export default {
2 index: 'Introduction',
3 - cli: 'CLI',
3 + _services: {
4 + type: 'separator',
5 + title: 'Platform'
6 + },
7 + deploy: 'Deploy',
8 + auth: 'Auth',
9 + mail: 'Mail',
10 + gresiq: 'GresIQ',
11 + _developer: {
12 + type: 'separator',
13 + title: 'Developer'
14 + },
15 + developer: 'Developer',
16 + _more: {
17 + type: 'separator',
18 + title: 'More'
19 + },
20 about: 'About'
21 }
content/about.mdx
+13 -1
@@ -1,3 +1,15 @@
1 # About
2
3 -This is the documentation page for smbCloud, the unified cloud platform for modern app deployment.
\ No newline at end of file
3 +These are the docs for **smbCloud Platform** — four services on one platform:
4 +[Deploy](/deploy), [Auth](/auth), [Mail](/mail), and [GresIQ](/gresiq).
5 +
6 +This site has two halves:
7 +
8 +- **Platform** — product documentation for each service: what it does and how to
9 + use it.
10 +- **[Developer](/developer)** — the technical reference for the CLI, tools, and
11 + SDKs you install and build against.
12 +
13 +The Developer pages for the CLI are pulled from the
14 +[smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli) repository, so they
15 +stay in step with the tool itself.
content/auth.mdx new
+30
@@ -0,0 +1,30 @@
1 +# Auth
2 +
3 +Auth is the identity and account service. It handles signing users in and
4 +managing their accounts, so you don't have to build that part yourself.
5 +
6 +## What you can do
7 +
8 +- Sign users in and let them create accounts
9 +- Manage sessions and accounts
10 +- Run hosted auth apps for your end-user accounts
11 +- Manage collaborators and shared access where it applies
12 +
13 +## Two kinds of accounts
14 +
15 +Keep these separate as you read:
16 +
17 +- **Your smbCloud account** — how you sign in to the platform.
18 +- **Auth app users** — the end users who sign in to *your* product through an
19 + auth app you run on smbCloud.
20 +
21 +When a screen or guide talks about "users", check which of the two it means.
22 +
23 +## Getting started
24 +
25 +1. Create an auth app for your product.
26 +2. Wire your app to its sign-in and account flows.
27 +3. Manage users and access from the console.
28 +
29 +Building against Auth from code? The SDKs live in the
30 +[Developer](/developer) section.
content/cli/_meta.js deleted
-3
@@ -1,3 +0,0 @@
1 -export default {
2 - setup: 'Setup'
3 -}
content/cli/index.mdx deleted
-7
@@ -1,7 +0,0 @@
1 ----
2 -asIndexPage: true
3 ----
4 -
5 -# CLI
6 -
7 -We use CLI program to interact with smbCloud resources.
\ No newline at end of file
content/cli/setup.mdx deleted
-23
@@ -1,23 +0,0 @@
1 -# Setup
2 -
3 -Our CLI interface is build with Rust and published on [Crates.io](https://crates.io/crates/smbcloud-cli).
4 -
5 -1. Setup your [Rust](https://www.rust-lang.org/tools/install).
6 -2. Install it globally with cargo: `cargo install smbcloud-cli`.
7 -3. Run `smb` command in your teminal to check your installation. You should get something like this:
8 -
9 -```
10 -╰─➤ smb
11 -Command line tool for creating and managing smbCloud resources.
12 -
13 -Usage: smb [OPTIONS] <COMMAND>
14 -
15 -Commands:
16 - login Login to your account. To create an account, visit https://smbcloud.xyz
17 - help Print this message or the help of the given subcommand(s)
18 -
19 -Options:
20 - -l, --log-level <LOG_LEVEL> Log level: trace, debug, info, warn, error, off
21 - -h, --help Print help
22 - -V, --version Print version
23 -```
\ No newline at end of file
content/deploy.mdx new
+35
@@ -0,0 +1,35 @@
1 +# Deploy
2 +
3 +Deploy is the app shipping layer. Ship your app with one command and keep
4 +infrastructure out of the way.
5 +
6 +## What you can do
7 +
8 +- Deploy NodeJS, Swift, and Ruby apps
9 +- Deploy from your terminal with a single command
10 +- Ship over an SSH-based flow
11 +- Cut versioned releases and roll back when you need to
12 +
13 +## How it fits together
14 +
15 +Deploy uses four ideas. Once they click, the rest follows.
16 +
17 +| Term | What it is |
18 +| --- | --- |
19 +| **Project** | The umbrella workspace in smbCloud. |
20 +| **Repo** | A git repository inside that workspace. |
21 +| **App** | A deployable unit inside a repo. |
22 +| **Deployment** | One deployment event for one app. |
23 +
24 +A repo can be a single app, or a monorepo with several deployable apps. The repo
25 +holds your source code; an app is the thing you actually deploy; a deployment is
26 +one release of one app.
27 +
28 +## Getting started
29 +
30 +1. Install the CLI — see [Developer → CLI](/developer/cli).
31 +2. Log in and point the CLI at your project.
32 +3. Run the deploy command from your repo.
33 +
34 +For non-interactive and CI deploys, see the CLI docs in the
35 +[Developer](/developer) section.
content/developer/_meta.js new
+4
@@ -0,0 +1,4 @@
1 +export default {
2 + cli: "CLI",
3 + contributing: "Contributing",
4 +}
content/developer/cli/_meta.js new
+6
@@ -0,0 +1,6 @@
1 +export default {
2 + native: "Native (Cargo)",
3 + homebrew: "Homebrew",
4 + npm: "npm",
5 + pypi: "PyPI",
6 +}
content/developer/cli/homebrew.mdx new
+44
@@ -0,0 +1,44 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/cli-install-homebrew.md (smbcloud-cli, main). */}
2 +
3 +# Homebrew Installation
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/cli-install-homebrew.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/cli-install-homebrew.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +## Install
13 +
14 +```bash
15 +brew tap smbcloudXYZ/tap
16 +brew install cli
17 +```
18 +
19 +## Verify
20 +
21 +```bash
22 +smb --version
23 +```
24 +
25 +## Upgrade
26 +
27 +```bash
28 +brew upgrade cli
29 +```
30 +
31 +## Uninstall
32 +
33 +```bash
34 +brew uninstall cli
35 +brew untap smbcloudXYZ/tap
36 +```
37 +
38 +## Pre-built binaries
39 +
40 +Homebrew installs a pre-built binary for your platform — no compiler required.
41 +
42 +You can also download any release directly from GitHub:
43 +
44 +https://github.com/smbcloudXYZ/smbcloud-cli/releases
content/developer/cli/index.mdx new
+50
@@ -0,0 +1,50 @@
1 +---
2 +asIndexPage: true
3 +title: CLI
4 +---
5 +
6 +# CLI
7 +
8 +`smb` is the smbCloud command-line tool. You use it to log in and to manage and
9 +deploy your smbCloud resources from the terminal.
10 +
11 +```text
12 +Usage: smb [OPTIONS] <COMMAND>
13 +
14 +Commands:
15 + login Login to your account. To create an account, visit https://smbcloud.xyz
16 + help Print this message or the help of the given subcommand(s)
17 +
18 +Options:
19 + -l, --log-level <LOG_LEVEL> Log level: trace, debug, info, warn, error, off
20 + -h, --help Print help
21 + -V, --version Print version
22 +```
23 +
24 +## Install
25 +
26 +Pick the channel that fits your setup — each one installs the same `smb` binary.
27 +
28 +| Channel | Best for | Guide |
29 +| --- | --- | --- |
30 +| Native (Cargo) | Rust users, building from source | [Native](/developer/cli/native) |
31 +| Homebrew | macOS / Linux, pre-built binary | [Homebrew](/developer/cli/homebrew) |
32 +| npm | JS toolchains (npm, pnpm, bun, yarn) | [npm](/developer/cli/npm) |
33 +| PyPI | Python toolchains (uv, pip) | [PyPI](/developer/cli/pypi) |
34 +
35 +After installing, check it worked:
36 +
37 +```bash
38 +smb --version
39 +```
40 +
41 +You can also download a binary for any release directly from the
42 +[GitHub releases page](https://github.com/smbcloudXYZ/smbcloud-cli/releases).
43 +
44 +import { Callout } from 'nextra/components'
45 +
46 +<Callout type="info">
47 + The install and contributing pages in this section are synced from the
48 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli) repository. Edit
49 + them there.
50 +</Callout>
content/developer/cli/native.mdx new
+61
@@ -0,0 +1,61 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/cli-install.md (smbcloud-cli, main). */}
2 +
3 +# Native Installation
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/cli-install.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/cli-install.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +Install directly from [crates.io](https://crates.io/crates/smbcloud-cli) using Cargo.
13 +
14 +## Prerequisites
15 +
16 +- [Rust](https://rustup.rs) (stable toolchain)
17 +- `CLI_CLIENT_SECRET` — required at compile time
18 +
19 +The `CLI_CLIENT_SECRET` value is baked into the binary at compile time. Contact [hej@setoelkahfi.se](mailto:hej@setoelkahfi.se) or check your smbCloud account dashboard to obtain it.
20 +
21 +## Install
22 +
23 +Export the secret, then install:
24 +
25 +```bash
26 +export CLI_CLIENT_SECRET=your_secret_here
27 +cargo install smbcloud-cli
28 +```
29 +
30 +## Verify
31 +
32 +```bash
33 +smb --version
34 +```
35 +
36 +## Upgrade
37 +
38 +```bash
39 +export CLI_CLIENT_SECRET=your_secret_here
40 +cargo install smbcloud-cli --force
41 +```
42 +
43 +## Uninstall
44 +
45 +```bash
46 +cargo uninstall smbcloud-cli
47 +```
48 +
49 +## Troubleshooting
50 +
51 +**`error: proc-macro derive panicked … Error loading .env file`**
52 +
53 +This error appears on older versions of `smbcloud-cli` (before `0.3.37`). Upgrade to the latest version — it reads `CLI_CLIENT_SECRET` directly from the environment at compile time and no longer requires a `.env` file.
54 +
55 +**`error[E0463]: can't find crate for std`**
56 +
57 +Your Rust toolchain is missing the target. Run:
58 +
59 +```bash
60 +rustup target add <target>
61 +```
content/developer/cli/npm.mdx new
+46
@@ -0,0 +1,46 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/cli-install-npm.md (smbcloud-cli, main). */}
2 +
3 +# npm Installation
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/cli-install-npm.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/cli-install-npm.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +## Install
13 +
14 +```bash
15 +npm install -g @smbcloud/cli
16 +```
17 +
18 +Also works with pnpm, bun, and yarn:
19 +
20 +```bash
21 +pnpm add -g @smbcloud/cli
22 +bun add -g @smbcloud/cli
23 +yarn global add @smbcloud/cli
24 +```
25 +
26 +## Verify
27 +
28 +```bash
29 +smb --version
30 +```
31 +
32 +## Upgrade
33 +
34 +```bash
35 +npm update -g @smbcloud/cli
36 +```
37 +
38 +## Uninstall
39 +
40 +```bash
41 +npm uninstall -g @smbcloud/cli
42 +```
43 +
44 +## Pre-built binaries
45 +
46 +All installation methods above use pre-built binaries. You can also download them directly from the [GitHub releases page](https://github.com/smbcloudXYZ/smbcloud-cli/releases) — useful for air-gapped environments, custom install scripts, or pinning to a specific version.
content/developer/cli/pypi.mdx new
+58
@@ -0,0 +1,58 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/cli-install-pypi.md (smbcloud-cli, main). */}
2 +
3 +# PyPI Installation
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/cli-install-pypi.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/cli-install-pypi.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +## Install
13 +
14 +Run once without a persistent install:
15 +
16 +```bash
17 +uvx --from smbcloud-cli smb
18 +```
19 +
20 +Install as a persistent tool:
21 +
22 +```bash
23 +uv tool install smbcloud-cli
24 +```
25 +
26 +Or with pip:
27 +
28 +```bash
29 +pip install smbcloud-cli
30 +```
31 +
32 +## Upgrade
33 +
34 +```bash
35 +uv tool upgrade smbcloud-cli
36 +```
37 +
38 +Or with pip:
39 +
40 +```bash
41 +pip install --upgrade smbcloud-cli
42 +```
43 +
44 +## Uninstall
45 +
46 +```bash
47 +uv tool uninstall smbcloud-cli
48 +```
49 +
50 +Or with pip:
51 +
52 +```bash
53 +pip uninstall smbcloud-cli
54 +```
55 +
56 +---
57 +
58 +All installation methods above use pre-built binaries — no Rust toolchain required. You can also download the binary directly from [GitHub Releases](https://github.com/smbcloudXYZ/smbcloud-cli/releases).
content/developer/contributing/_meta.js new
+5
@@ -0,0 +1,5 @@
1 +export default {
2 + debugging: "VSCode Debugging",
3 + development: "Releasing & ADRs",
4 + gems: "Publishing the gem",
5 +}
content/developer/contributing/debugging.mdx new
+38
@@ -0,0 +1,38 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/debugging.md (smbcloud-cli, main). */}
2 +
3 +# VSCode Debugging
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/debugging.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/debugging.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +To debug the app on VSCode, use [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) and [cargo debugger](https://github.com/jkelleyrtp/cargo-debugger).
13 +
14 +```bash
15 +$ cargo debugger --package smbcloud-cli -- account signup
16 +```
17 +
18 +## Environment
19 +
20 +Default environment is production. To run against dev environemt:
21 +
22 +```bash
23 +$ cargo run -p smbcloud-cli -- -e dev account login
24 +```
25 +
26 +Example debug the dev environment:
27 +
28 +```bash
29 +$ cargo debugger --package smbcloud-cli -- -e dev account login
30 +```
31 +
32 +## Run from different directory
33 +
34 +To run from a different directory, use the `--manifest-path` flag and `--package` flag. :
35 +
36 +```bash
37 +$ cargo debugger --manifest-path .../path/to/smbcloud-cli/Cargo.toml --package smbcloud-cli -- -e dev account login
38 +```
content/developer/contributing/development.mdx new
+30
@@ -0,0 +1,30 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/development.md (smbcloud-cli, main). */}
2 +
3 +# ADR
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/development.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/development.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +This repo uses [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture-decision-record) in the `adr` folder.
13 +
14 +# Publish Update
15 +
16 +There's no GitHub action to automatically publish the package for now. Publishing task can also be done locally.
17 +
18 +To update the crate in the [crate.io](https://crate.io), use [cargo workspaces](https://github.com/pksunkara/cargo-workspaces) subcommand.
19 +
20 +Steps to publish new package:
21 +
22 +```bash
23 +$ cargo workspaces publish --publish-as-is
24 +```
25 +
26 +It will ask whether should bump the vesions of the packages or not. To update version separately:
27 +
28 +```bash
29 +$ cargo workspaces version
30 +```
content/developer/contributing/gems.mdx new
+85
@@ -0,0 +1,85 @@
1 +{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from docs/gems.md (smbcloud-cli, main). */}
2 +
3 +# Publishing the `smbcloud-model` gem
4 +
5 +import { Callout } from 'nextra/components'
6 +
7 +<Callout type="info">
8 + Synced from [`docs/gems.md`](https://github.com/smbcloudXYZ/smbcloud-cli/blob/main/docs/gems.md) on the `main` branch of
9 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.
10 +</Callout>
11 +
12 +The gem wraps the `smbcloud-model` Rust crate via a native extension. Publishing requires coordinating the Rust crate release and the gem release in order.
13 +
14 +## Prerequisites
15 +
16 +- [Rust toolchain](https://rustup.rs) installed
17 +- `bundler` and `gem` CLI available
18 +- RubyGems account with push access to `smbcloud-model`
19 +
20 +---
21 +
22 +## Steps
23 +
24 +### 1. Publish the Rust crate
25 +
26 +Publish `smbcloud-model` to crates.io first. The gem's native extension depends on it.
27 +
28 +```sh
29 +cargo publish -p smbcloud-model
30 +```
31 +
32 +### 2. Update the Cargo dependency
33 +
34 +Switch `gems/model/ext/model/Cargo.toml` from the local path to the published version:
35 +
36 +```toml
37 +# Before (development)
38 +smbcloud-model = { path = "./../../../../crates/smbcloud-model" }
39 +
40 +# After (release) — match the version just published
41 +smbcloud-model = "0.3"
42 +```
43 +
44 +### 3. Sync the gem version
45 +
46 +Set `gems/model/lib/model/version.rb` to match the `smbcloud-model` crate version:
47 +
48 +```ruby
49 +module Model
50 + VERSION = '0.3.31'
51 +end
52 +```
53 +
54 +### 4. Compile the native extension
55 +
56 +```sh
57 +cd gems/model
58 +bundle exec rake compile
59 +```
60 +
61 +### 5. Build the gem
62 +
63 +```sh
64 +bundle exec rake build
65 +```
66 +
67 +This produces `pkg/smbcloud-model-<version>.gem`.
68 +
69 +### 6. Publish the gem
70 +
71 +```sh
72 +gem push pkg/smbcloud-model-<version>.gem
73 +```
74 +
75 +---
76 +
77 +## Development workflow
78 +
79 +To work against the local crate instead of the published one, use the path dependency:
80 +
81 +```toml
82 +smbcloud-model = { path = "./../../../../crates/smbcloud-model" }
83 +```
84 +
85 +Remember to revert this before publishing.
content/developer/contributing/index.mdx new
+24
@@ -0,0 +1,24 @@
1 +---
2 +asIndexPage: true
3 +title: Contributing
4 +---
5 +
6 +# Contributing
7 +
8 +Working on the smbCloud CLI and its packages — building, debugging, and
9 +releasing.
10 +
11 +- [VSCode Debugging](/developer/contributing/debugging) — debug `smb` locally and
12 + switch between the production and dev environments.
13 +- [Releasing & ADRs](/developer/contributing/development) — how the crate is
14 + published and where architecture decisions live.
15 +- [Publishing the gem](/developer/contributing/gems) — release the
16 + `smbcloud-model` gem alongside its Rust crate.
17 +
18 +import { Callout } from 'nextra/components'
19 +
20 +<Callout type="info">
21 + These pages are synced from the
22 + [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli) repository
23 + (`main` branch). Edit them at the source.
24 +</Callout>
content/developer/index.mdx new
+28
@@ -0,0 +1,28 @@
1 +---
2 +asIndexPage: true
3 +title: Developer
4 +---
5 +
6 +# Developer
7 +
8 +The technical reference for building against smbCloud — the command-line tool,
9 +the local tooling, and the SDKs.
10 +
11 +import { Cards } from 'nextra/components'
12 +
13 +<Cards>
14 + <Cards.Card title="CLI" href="/developer/cli" arrow>
15 + Install and use `smb`, the smbCloud command-line tool.
16 + </Cards.Card>
17 + <Cards.Card title="Contributing" href="/developer/contributing" arrow>
18 + Build, debug, and release the CLI and its packages.
19 + </Cards.Card>
20 +</Cards>
21 +
22 +## How these docs stay current
23 +
24 +The CLI and contributing pages here are **pulled from the
25 +[`docs/`](https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/docs) folder of
26 +the [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli) repository**
27 +(`main` branch). They're synced into this site, so they track the tool itself —
28 +edit them at the source, not here.
content/gresiq.mdx new
+22
@@ -0,0 +1,22 @@
1 +# GresIQ
2 +
3 +GresIQ is the database service — a managed, PostgreSQL-oriented database for your
4 +app.
5 +
6 +## What you can do
7 +
8 +- Run a managed PostgreSQL-oriented database
9 +- Configure the service and get connection details
10 +- Reach your data through smbCloud Platform access patterns
11 +
12 +## How it fits together
13 +
14 +GresIQ is the data layer for your app. You set up the service, grab its
15 +connection details, and connect your app the way you would to any PostgreSQL
16 +database.
17 +
18 +## Getting started
19 +
20 +1. Create a GresIQ database.
21 +2. Open its connection details.
22 +3. Connect your app and start querying.
content/index.mdx
+39 -5
@@ -1,7 +1,41 @@
1 -# smbCloud Documentation
2 -
3 -Find technical documentation for smbCloud services, SDKs and toolkits, use cases, scenarios, and tasks. Browse user guides, developer guides, tutorials, and API references.
1 +---
2 +title: Introduction
3 +---
4
5 -## What is smbCloud?
5 +# smbCloud Platform
6
7 -A **simple**, **powerful** and **flexible** cloud platform for the next generation web.
7 +**Four services. One platform.** Enterprise power at startup velocity.
8 +
9 +smbCloud is the platform you build your product on. It bundles the pieces most
10 +teams stitch together by hand — shipping apps, signing users in, routing mail,
11 +and running a database — into one place, so you can stay focused on what you're
12 +actually building.
13 +
14 +## The services
15 +
16 +import { Cards } from 'nextra/components'
17 +
18 +<Cards>
19 + <Cards.Card title="Deploy" href="/deploy" arrow>
20 + Ship NodeJS, Swift, and Ruby apps with one command.
21 + </Cards.Card>
22 + <Cards.Card title="Auth" href="/auth" arrow>
23 + Sign-in, accounts, and hosted auth for your users.
24 + </Cards.Card>
25 + <Cards.Card title="Mail" href="/mail" arrow>
26 + Domain mail routing, forwarding, and stored messages.
27 + </Cards.Card>
28 + <Cards.Card title="GresIQ" href="/gresiq" arrow>
29 + A managed PostgreSQL database for your app.
30 + </Cards.Card>
31 +</Cards>
32 +
33 +## Where to go next
34 +
35 +- New here? Start with the service that matches what you're trying to do.
36 +- Building against smbCloud? The [Developer](/developer) section covers the CLI,
37 + tools, and SDKs.
38 +
39 +Looking for product help by service, head to **Deploy**, **Auth**, **Mail**, or
40 +**GresIQ** above. For the command-line tool and everything you install locally,
41 +see [Developer](/developer).
content/mail.mdx new
+30
@@ -0,0 +1,30 @@
1 +# Mail
2 +
3 +Mail is the domain mail-routing product. It's forwarding-first today, and it can
4 +now store inbound message history too.
5 +
6 +## What you can do
7 +
8 +- Run one Mail app per domain
9 +- Set up many inbox routes on a Mail app
10 +- Forward inbound mail where it needs to go
11 +- Store inbound message history
12 +
13 +## How it fits together
14 +
15 +- A project can have many Mail apps.
16 +- One Mail app maps to one domain.
17 +- One Mail app can have many inbox routes.
18 +
19 +Day to day, you work with **inboxes**, **forwarding**, and **stored messages**.
20 +The domain setup — DNS, bucket, prefix, and shared routing — lives on the Mail
21 +app's setup page, out of the way of everyday inbox work.
22 +
23 +## Getting started
24 +
25 +1. Create a Mail app for your domain.
26 +2. Complete the domain setup (DNS and routing) on the Mail app's setup page.
27 +3. Add inbox routes and forwarding.
28 +
29 +Mail is forwarding-first — it's not a full hosted mailbox suite. Stored messages
30 +add history on top of routing.
package.json
+1
@@ -1,6 +1,7 @@
1 {
2 "scripts": {
3 "dev": "next",
4 + "sync:developer": "node scripts/sync-developer-docs.mjs",
5 "build": "next build",
6 "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind",
7 "start": "next start",
scripts/sync-developer-docs.mjs new
+119
@@ -0,0 +1,119 @@
1 +#!/usr/bin/env node
2 +/**
3 + * Sync the /developer docs from the smbcloud-cli repository.
4 + *
5 + * The CLI / tooling documentation lives in `docs/` of smbcloud-cli and is the
6 + * source of truth. This script pulls those files into content/developer/ so the
7 + * docs site tracks the tool. Synced files are committed (vendored) so the site
8 + * builds on CI without network access — re-run this script to refresh them.
9 + *
10 + * pnpm sync:developer
11 + *
12 + * Hand-written index pages (content/developer/**\/index.mdx) are NOT touched.
13 + * Only the files listed in MANIFEST and the generated _meta.js are written.
14 + */
15 +import { execSync } from 'node:child_process'
16 +import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
17 +import { tmpdir } from 'node:os'
18 +import { join, dirname } from 'node:path'
19 +import { fileURLToPath } from 'node:url'
20 +
21 +const REPO = 'https://github.com/smbcloudXYZ/smbcloud-cli.git'
22 +const BRANCH = 'main'
23 +const SRC_DIR = 'docs'
24 +
25 +const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
26 +const DEST = join(ROOT, 'content', 'developer')
27 +
28 +// Source file -> where it lands and how it's labelled in the sidebar.
29 +// `mail-service.md` is intentionally excluded: it's a scratch notes file in the
30 +// source repo, not publishable documentation.
31 +const MANIFEST = {
32 + cli: {
33 + title: 'CLI',
34 + pages: [
35 + { src: 'cli-install.md', slug: 'native', title: 'Native (Cargo)' },
36 + { src: 'cli-install-homebrew.md', slug: 'homebrew', title: 'Homebrew' },
37 + { src: 'cli-install-npm.md', slug: 'npm', title: 'npm' },
38 + { src: 'cli-install-pypi.md', slug: 'pypi', title: 'PyPI' }
39 + ]
40 + },
41 + contributing: {
42 + title: 'Contributing',
43 + pages: [
44 + { src: 'debugging.md', slug: 'debugging', title: 'VSCode Debugging' },
45 + { src: 'development.md', slug: 'development', title: 'Releasing & ADRs' },
46 + { src: 'gems.md', slug: 'gems', title: 'Publishing the gem' }
47 + ]
48 + }
49 +}
50 +
51 +const blobUrl = src =>
52 + `https://github.com/smbcloudXYZ/smbcloud-cli/blob/${BRANCH}/${SRC_DIR}/${src}`
53 +
54 +/** Wrap synced markdown: header note + a source callout after the first H1. */
55 +function decorate(markdown, src) {
56 + const note = `{/* AUTO-GENERATED — do not edit. Synced by scripts/sync-developer-docs.mjs from ${SRC_DIR}/${src} (smbcloud-cli, ${BRANCH}). */}`
57 + const callout = [
58 + "import { Callout } from 'nextra/components'",
59 + '',
60 + '<Callout type="info">',
61 + ` Synced from [\`${SRC_DIR}/${src}\`](${blobUrl(src)}) on the \`${BRANCH}\` branch of`,
62 + ' [smbcloud-cli](https://github.com/smbcloudXYZ/smbcloud-cli). Edit it there.',
63 + '</Callout>'
64 + ].join('\n')
65 +
66 + const lines = markdown.replace(/\r\n/g, '\n').trimEnd().split('\n')
67 + const h1 = lines.findIndex(l => /^#\s/.test(l))
68 + if (h1 === -1) {
69 + return `${note}\n\n${callout}\n\n${lines.join('\n')}\n`
70 + }
71 + const before = lines.slice(0, h1 + 1).join('\n')
72 + const after = lines.slice(h1 + 1).join('\n')
73 + return `${note}\n\n${before}\n\n${callout}\n${after}\n`
74 +}
75 +
76 +// Note: the folder's own index page uses `asIndexPage` frontmatter, so it must
77 +// NOT be listed as an `index` key here — Nextra surfaces it via the parent.
78 +function metaFile(pages) {
79 + const entries = pages.map(p => ` ${p.slug}: ${JSON.stringify(p.title)},`)
80 + return `export default {\n${entries.join('\n')}\n}\n`
81 +}
82 +
83 +function main() {
84 + const tmp = mkdtempSync(join(tmpdir(), 'smb-cli-docs-'))
85 + try {
86 + console.log(`Cloning ${REPO} (${BRANCH}, sparse: ${SRC_DIR})…`)
87 + execSync(
88 + `git clone --depth 1 --branch ${BRANCH} --filter=blob:none --sparse ${REPO} "${tmp}"`,
89 + { stdio: 'inherit' }
90 + )
91 + execSync(`git -C "${tmp}" sparse-checkout set ${SRC_DIR}`, { stdio: 'inherit' })
92 +
93 + let count = 0
94 + for (const [section, { title, pages }] of Object.entries(MANIFEST)) {
95 + const dir = join(DEST, section)
96 + mkdirSync(dir, { recursive: true })
97 + for (const page of pages) {
98 + const raw = readFileSync(join(tmp, SRC_DIR, page.src), 'utf8')
99 + writeFileSync(join(dir, `${page.slug}.mdx`), decorate(raw, page.src))
100 + count++
101 + }
102 + writeFileSync(join(dir, '_meta.js'), metaFile(pages))
103 + console.log(` ${section}: ${pages.length} pages (${title})`)
104 + }
105 +
106 + // Top-level developer nav: each section (the overview is asIndexPage).
107 + const top = []
108 + for (const [section, { title }] of Object.entries(MANIFEST)) {
109 + top.push(` ${section}: ${JSON.stringify(title)},`)
110 + }
111 + writeFileSync(join(DEST, '_meta.js'), `export default {\n${top.join('\n')}\n}\n`)
112 +
113 + console.log(`\nSynced ${count} pages into content/developer/.`)
114 + } finally {
115 + rmSync(tmp, { recursive: true, force: true })
116 + }
117 +}
118 +
119 +main()