fix: pin mintlify version + fix broken links

ra0x3 · ra0x3 · commit d3a3900fd6b0 · 2026-04-01T16:55:34.000-07:00
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -134,11 +134,12 @@ jobs:
           node-version: "20.17.0"
 
       - name: Install Mintlify CLI
-        run: npm install --global mint
+        # Pin Mintlify to keep docs validation reproducible across CI runs.
+        run: npm install --global mintlify@4.0.373
 
       - name: Validate Docs
         working-directory: docs
-        run: mint validate
+        run: mintlify broken-links
 
   rustdoc:
     name: Rust Doc
diff --git a/docs/docs.json b/docs/docs.json
@@ -8,17 +8,11 @@
     "light": "#679bfc",
     "dark": "#4463a0"
   },
-  "favicon": "https://i.imgur.com/hqwS335.png",
-  "logo": {
-    "light": "https://i.imgur.com/BwszZ66.png",
-    "dark": "https://i.imgur.com/BwszZ66.png",
-    "href": "https://docs.sysg.dev"
-  },
   "navbar": {
     "links": [
       {
         "label": "Documentation",
-        "href": "/intro"
+        "href": "https://sysg.dev/intro"
       },
       {
         "label": "GitHub",
@@ -28,29 +22,29 @@
     "primary": {
       "type": "button",
       "label": "Quickstart",
-      "href": "/quickstart"
+      "href": "https://sysg.dev/quickstart"
     }
   },
   "footer": {
     "socials": {
       "github": "https://github.com/ra0x3/systemg",
-      "website": "https://docs.sysg.dev"
+      "website": "https://sysg.dev"
     },
     "links": [
       {
         "header": "Docs",
         "items": [
           {
             "label": "Introduction",
-            "href": "/intro"
+            "href": "https://sysg.dev/intro"
           },
           {
             "label": "Quickstart",
-            "href": "/quickstart"
+            "href": "https://sysg.dev/quickstart"
           },
           {
             "label": "Examples",
-            "href": "/examples"
+            "href": "https://sysg.dev/examples"
           }
         ]
       },
@@ -63,7 +57,7 @@
           },
           {
             "label": "docs.sysg.dev",
-            "href": "https://docs.sysg.dev"
+            "href": "https://sysg.dev"
           }
         ]
       }
diff --git a/docs/examples/index.mdx b/docs/examples/index.mdx
@@ -6,19 +6,19 @@ title: Examples
 
 Working examples demonstrating systemg features.
 
-## [Hello World](hello-world)
+## [Hello World](/examples/hello-world)
 
 Minimal service configuration.
 
-## [CRUD Application](crud)
+## [CRUD Application](/examples/crud)
 
 Simple FastAPI CRUD service for testing systemg service management.
 
-## [Units](units)
+## [Units](/examples/units)
 
 Practical command-based unit examples, staged under `~/.local/share/systemg/units/`.
 
-## [Orchestrator](orchestrator)
+## [Orchestrator](/examples/orchestrator)
 
 Multi-agent task execution with Redis coordination and DAG scheduling.
 
@@ -38,5 +38,5 @@ Each example includes:
 
 ## See also
 
-- [Quickstart](../quickstart) - Quick introduction
-- [Configuration](../how-it-works/configuration) - Full reference
+- [Quickstart](/quickstart) - Quick introduction
+- [Configuration](/how-it-works/configuration) - Full reference
diff --git a/docs/how-it-works/commands/inspect.mdx b/docs/how-it-works/commands/inspect.mdx
@@ -66,5 +66,5 @@ $ sysg inspect -s api --stream 24h
 
 ## See also
 
-- [`status`](status) - Quick service overview
-- [`logs`](logs) - View service output
+- [`status`](/how-it-works/commands/status) - Quick service overview
+- [`logs`](/how-it-works/commands/logs) - View service output
diff --git a/docs/how-it-works/commands/logs.mdx b/docs/how-it-works/commands/logs.mdx
@@ -89,5 +89,5 @@ Logs are stored in `~/.local/share/systemg/logs/`:
 
 ## See also
 
-- [`status`](status) - Check service health
-- [`inspect`](inspect) - View detailed metrics
+- [`status`](/how-it-works/commands/status) - Check service health
+- [`inspect`](/how-it-works/commands/inspect) - View detailed metrics
diff --git a/docs/how-it-works/commands/purge.mdx b/docs/how-it-works/commands/purge.mdx
@@ -44,5 +44,5 @@ $ All systemg state has been purged
 
 ## See also
 
-- [`stop`](stop) - Stop services without removing state
-- [`start`](start) - Start fresh after purging
+- [`stop`](/how-it-works/commands/stop) - Stop services without removing state
+- [`start`](/how-it-works/commands/start) - Start fresh after purging
diff --git a/docs/how-it-works/commands/restart.mdx b/docs/how-it-works/commands/restart.mdx
@@ -106,6 +106,6 @@ This keeps restart behavior explicit when supervisor detection is unavailable.
 
 ## See also
 
-- [`start`](start) - Launch services
-- [`stop`](stop) - Stop services
-- [Deployment strategies](../configuration#deployment-strategies)
+- [`start`](/how-it-works/commands/start) - Launch services
+- [`stop`](/how-it-works/commands/stop) - Stop services
+- [Deployment strategies](/how-it-works/configuration#deployment-strategies)
diff --git a/docs/how-it-works/commands/spawn.mdx b/docs/how-it-works/commands/spawn.mdx
@@ -75,5 +75,5 @@ The parent can then spawn up to 10 child processes dynamically.
 
 ## See also
 
-- [Spawn configuration](../configuration#spawn-settings)
-- [`status`](status) - View spawned processes
+- [Spawn configuration](/how-it-works/configuration#spawn-settings)
+- [`status`](/how-it-works/commands/status) - View spawned processes
diff --git a/docs/how-it-works/commands/start-vs-spawn.mdx b/docs/how-it-works/commands/start-vs-spawn.mdx
@@ -102,6 +102,6 @@ while job := queue.pop():
 
 ## See also
 
-- [`start`](start) - Launch services
-- [`spawn`](spawn) - Deprecated command reference
-- [Configuration](../configuration) - Service definitions
+- [`start`](/how-it-works/commands/start) - Launch services
+- [`spawn`](/how-it-works/commands/spawn) - Deprecated command reference
+- [Configuration](/how-it-works/configuration) - Service definitions
diff --git a/docs/how-it-works/commands/start.mdx b/docs/how-it-works/commands/start.mdx
@@ -193,6 +193,6 @@ In daemon mode, the supervisor monitors services and handles restarts according
 
 ## See also
 
-- [`stop`](stop) - Stop running services
-- [`status`](status) - Check service health
-- [`restart`](restart) - Restart services
+- [`stop`](/how-it-works/commands/stop) - Stop running services
+- [`status`](/how-it-works/commands/status) - Check service health
+- [`restart`](/how-it-works/commands/restart) - Restart services
diff --git a/docs/how-it-works/commands/status.mdx b/docs/how-it-works/commands/status.mdx
@@ -82,5 +82,5 @@ $ sysg status --stream 5
 
 ## See also
 
-- [`logs`](logs) - View service output
-- [`restart`](restart) - Restart services
+- [`logs`](/how-it-works/commands/logs) - View service output
+- [`restart`](/how-it-works/commands/restart) - Restart services
diff --git a/docs/how-it-works/commands/stop.mdx b/docs/how-it-works/commands/stop.mdx
@@ -71,5 +71,5 @@ When stopping a single service, its dependents keep running. Only crashes trigge
 
 ## See also
 
-- [`start`](start) - Launch services
-- [`restart`](restart) - Restart services
+- [`start`](/how-it-works/commands/start) - Launch services
+- [`restart`](/how-it-works/commands/restart) - Restart services
diff --git a/docs/how-it-works/index.mdx b/docs/how-it-works/index.mdx
@@ -49,10 +49,10 @@ All runtime data lives in one place:
 
 ## Topics
 
-- [Commands](commands) - CLI reference
-- [Configuration](configuration) - Service definitions
-- [Cron](cron) - Scheduled tasks
-- [Webhooks](webhooks) - Lifecycle hooks
-- [State](state) - Runtime files
-- [Logs](logs) - Supervisor logs
-- [Privileged Mode](privileged-mode) - System features
+- [Commands](/how-it-works/commands) - CLI reference
+- [Configuration](/how-it-works/configuration) - Service definitions
+- [Cron](/how-it-works/cron) - Scheduled tasks
+- [Webhooks](/how-it-works/webhooks) - Lifecycle hooks
+- [State](/how-it-works/state) - Runtime files
+- [Logs](/how-it-works/logs) - Supervisor logs
+- [Privileged Mode](/how-it-works/privileged-mode) - System features
diff --git a/docs/how-it-works/logs.mdx b/docs/how-it-works/logs.mdx
@@ -111,5 +111,5 @@ $ mv ~/.local/share/systemg/logs/supervisor.log ~/.local/share/systemg/logs/supe
 
 ## See also
 
-- [`logs`](commands/logs) - View service output
-- [`status`](commands/status) - Check service health
+- [`logs`](/how-it-works/commands/logs) - View service output
+- [`status`](/how-it-works/commands/status) - Check service health
diff --git a/docs/how-it-works/privileged-mode.mdx b/docs/how-it-works/privileged-mode.mdx
@@ -141,5 +141,5 @@ services:
 
 ## See also
 
-- [Security](../security) - Security considerations
-- [Configuration](configuration) - Service definitions
+- [Security](/security) - Security considerations
+- [Configuration](/how-it-works/configuration) - Service definitions
diff --git a/docs/how-it-works/state.mdx b/docs/how-it-works/state.mdx
@@ -54,5 +54,5 @@ Clean shutdown removes `sysg.pid` and `control.sock`. Stale files after crash? R
 
 ## See also
 
-- [`purge`](commands/purge) - Clear all state
-- [How It Works](./) - Architecture overview
+- [`purge`](/how-it-works/commands/purge) - Clear all state
+- [How It Works](/how-it-works) - Architecture overview
diff --git a/docs/index.mdx b/docs/index.mdx
@@ -3,10 +3,6 @@ title: systemg
 description: A general-purpose program composer.
 ---
 
-# systemg
-
-A general-purpose program composer.
-
 systemg runs your service graph from a single YAML file.
 
 <CodeGroup>

Original file line number	Diff line number	Diff line change
`@@ -8,17 +8,11 @@`
`8`	`8`	`"light": "#679bfc",`
`9`	`9`	`"dark": "#4463a0"`
`10`	`10`	`},`
`11`		`- "favicon": "https://i.imgur.com/hqwS335.png",`
`12`		`- "logo": {`
`13`		`- "light": "https://i.imgur.com/BwszZ66.png",`
`14`		`- "dark": "https://i.imgur.com/BwszZ66.png",`
`15`		`- "href": "https://docs.sysg.dev"`
`16`		`- },`
`17`	`11`	`"navbar": {`
`18`	`12`	`"links": [`
`19`	`13`	`{`
`20`	`14`	`"label": "Documentation",`
`21`		`- "href": "/intro"`
	`15`	`+ "href": "https://sysg.dev/intro"`
`22`	`16`	`},`
`23`	`17`	`{`
`24`	`18`	`"label": "GitHub",`
`@@ -28,29 +22,29 @@`
`28`	`22`	`"primary": {`
`29`	`23`	`"type": "button",`
`30`	`24`	`"label": "Quickstart",`
`31`		`- "href": "/quickstart"`
	`25`	`+ "href": "https://sysg.dev/quickstart"`
`32`	`26`	`}`
`33`	`27`	`},`
`34`	`28`	`"footer": {`
`35`	`29`	`"socials": {`
`36`	`30`	`"github": "https://github.com/ra0x3/systemg",`
`37`		`- "website": "https://docs.sysg.dev"`
	`31`	`+ "website": "https://sysg.dev"`
`38`	`32`	`},`
`39`	`33`	`"links": [`
`40`	`34`	`{`
`41`	`35`	`"header": "Docs",`
`42`	`36`	`"items": [`
`43`	`37`	`{`
`44`	`38`	`"label": "Introduction",`
`45`		`- "href": "/intro"`
	`39`	`+ "href": "https://sysg.dev/intro"`
`46`	`40`	`},`
`47`	`41`	`{`
`48`	`42`	`"label": "Quickstart",`
`49`		`- "href": "/quickstart"`
	`43`	`+ "href": "https://sysg.dev/quickstart"`
`50`	`44`	`},`
`51`	`45`	`{`
`52`	`46`	`"label": "Examples",`
`53`		`- "href": "/examples"`
	`47`	`+ "href": "https://sysg.dev/examples"`
`54`	`48`	`}`
`55`	`49`	`]`
`56`	`50`	`},`
`@@ -63,7 +57,7 @@`
`63`	`57`	`},`
`64`	`58`	`{`
`65`	`59`	`"label": "docs.sysg.dev",`
`66`		`- "href": "https://docs.sysg.dev"`
	`60`	`+ "href": "https://sysg.dev"`
`67`	`61`	`}`
`68`	`62`	`]`
`69`	`63`	`}`