From 42da541407f8934ce4aa00d2aa7054ed66a24092 Mon Sep 17 00:00:00 2001
From: raiseCatError <315733358+raiseCatError@users.noreply.github.com>
Date: Sun, 11 Oct 2026 08:24:07 +0530
Subject: [PATCH 1/6] docs: implement Starlight documentation website
---
.github/workflows/deploy.yml | 82 +
site/.gitignore | 21 +
site/.vscode/extensions.json | 4 +
site/.vscode/launch.json | 11 +
site/AGENTS.md | 22 +
site/CLAUDE.md | 1 +
site/DEVELOPMENT.md | 54 +
site/README.md | 49 +
site/astro.config.mjs | 57 +
site/package-lock.json | 5775 +++++++++++++++++
site/package.json | 19 +
site/public/favicon.svg | 1 +
site/src/assets/houston.webp | Bin 0 -> 98506 bytes
site/src/components/Availability.astro | 37 +
site/src/content.config.ts | 7 +
site/src/content/docs/guides/agents.mdx | 34 +
site/src/content/docs/guides/composer.mdx | 41 +
site/src/content/docs/guides/concepts.mdx | 39 +
.../content/docs/guides/context-engine.mdx | 58 +
.../src/content/docs/guides/customization.mdx | 64 +
.../content/docs/guides/getting-started.mdx | 57 +
site/src/content/docs/guides/sessions.mdx | 29 +
site/src/content/docs/guides/tools.mdx | 40 +
site/src/content/docs/guides/transcripts.mdx | 47 +
site/src/content/docs/index.mdx | 40 +
.../src/content/docs/project/architecture.mdx | 33 +
site/src/content/docs/project/roadmap.mdx | 53 +
site/src/content/docs/reference/commands.mdx | 44 +
site/src/custom.css | 28 +
site/src/styles/global.css | 1 +
site/tsconfig.json | 5 +
31 files changed, 6753 insertions(+)
create mode 100644 .github/workflows/deploy.yml
create mode 100644 site/.gitignore
create mode 100644 site/.vscode/extensions.json
create mode 100644 site/.vscode/launch.json
create mode 100644 site/AGENTS.md
create mode 120000 site/CLAUDE.md
create mode 100644 site/DEVELOPMENT.md
create mode 100644 site/README.md
create mode 100644 site/astro.config.mjs
create mode 100644 site/package-lock.json
create mode 100644 site/package.json
create mode 100644 site/public/favicon.svg
create mode 100644 site/src/assets/houston.webp
create mode 100644 site/src/components/Availability.astro
create mode 100644 site/src/content.config.ts
create mode 100644 site/src/content/docs/guides/agents.mdx
create mode 100644 site/src/content/docs/guides/composer.mdx
create mode 100644 site/src/content/docs/guides/concepts.mdx
create mode 100644 site/src/content/docs/guides/context-engine.mdx
create mode 100644 site/src/content/docs/guides/customization.mdx
create mode 100644 site/src/content/docs/guides/getting-started.mdx
create mode 100644 site/src/content/docs/guides/sessions.mdx
create mode 100644 site/src/content/docs/guides/tools.mdx
create mode 100644 site/src/content/docs/guides/transcripts.mdx
create mode 100644 site/src/content/docs/index.mdx
create mode 100644 site/src/content/docs/project/architecture.mdx
create mode 100644 site/src/content/docs/project/roadmap.mdx
create mode 100644 site/src/content/docs/reference/commands.mdx
create mode 100644 site/src/custom.css
create mode 100644 site/src/styles/global.css
create mode 100644 site/tsconfig.json
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
new file mode 100644
index 00000000..f469b891
--- /dev/null
+++ b/.github/workflows/deploy.yml
@@ -0,0 +1,82 @@
+name: Deploy Documentation Site to GitHub Pages
+
+on:
+ # Trigger the workflow every time you push to the `docs/github-pages-site` branch
+ push:
+ branches: [ docs/github-pages-site ]
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+env:
+ BUILD_PATH: "./site" # Path to the Astro project
+
+jobs:
+ build:
+ name: Build
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+ - name: Detect package manager
+ id: detect-package-manager
+ run: |
+ if [ -f "${{ env.BUILD_PATH }}/yarn.lock" ]; then
+ echo "manager=yarn" >> $GITHUB_OUTPUT
+ echo "command=install" >> $GITHUB_OUTPUT
+ echo "runner=yarn" >> $GITHUB_OUTPUT
+ exit 0
+ elif [ -f "${{ env.BUILD_PATH }}/package.json" ]; then
+ echo "manager=npm" >> $GITHUB_OUTPUT
+ echo "command=ci" >> $GITHUB_OUTPUT
+ echo "runner=npx --no-install" >> $GITHUB_OUTPUT
+ exit 0
+ else
+ echo "Unable to determine package manager"
+ exit 1
+ fi
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+ cache: ${{ steps.detect-package-manager.outputs.manager }}
+ cache-dependency-path: ${{ env.BUILD_PATH }}/package-lock.json
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Install dependencies
+ run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
+ working-directory: ${{ env.BUILD_PATH }}
+ - name: Build with Astro
+ run: |
+ ${{ steps.detect-package-manager.outputs.runner }} astro build \
+ --site "${{ steps.pages.outputs.origin }}" \
+ --base "${{ steps.pages.outputs.base_path }}"
+ working-directory: ${{ env.BUILD_PATH }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ${{ env.BUILD_PATH }}/dist
+
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ needs: build
+ runs-on: ubuntu-latest
+ name: Deploy
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/site/.gitignore b/site/.gitignore
new file mode 100644
index 00000000..6240da8b
--- /dev/null
+++ b/site/.gitignore
@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
diff --git a/site/.vscode/extensions.json b/site/.vscode/extensions.json
new file mode 100644
index 00000000..22a15055
--- /dev/null
+++ b/site/.vscode/extensions.json
@@ -0,0 +1,4 @@
+{
+ "recommendations": ["astro-build.astro-vscode"],
+ "unwantedRecommendations": []
+}
diff --git a/site/.vscode/launch.json b/site/.vscode/launch.json
new file mode 100644
index 00000000..d6422097
--- /dev/null
+++ b/site/.vscode/launch.json
@@ -0,0 +1,11 @@
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "command": "./node_modules/.bin/astro dev",
+ "name": "Development server",
+ "request": "launch",
+ "type": "node-terminal"
+ }
+ ]
+}
diff --git a/site/AGENTS.md b/site/AGENTS.md
new file mode 100644
index 00000000..c5ff4297
--- /dev/null
+++ b/site/AGENTS.md
@@ -0,0 +1,22 @@
+## Development
+
+When starting the dev server, use background mode:
+
+```
+astro dev --background
+```
+
+Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
+
+## Documentation
+
+Full documentation: https://docs.astro.build
+
+Consult these guides before working on related tasks:
+
+- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
+- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
+- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
+- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)
diff --git a/site/CLAUDE.md b/site/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/site/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/site/DEVELOPMENT.md b/site/DEVELOPMENT.md
new file mode 100644
index 00000000..14932562
--- /dev/null
+++ b/site/DEVELOPMENT.md
@@ -0,0 +1,54 @@
+# NMSh Website Development Record
+
+## 1. Stack and Rationale
+- **Framework**: Astro with the Starlight template.
+- **Why**: Starlight is the standard for modern documentation sites. It provides out-of-the-box support for Markdown/MDX, excellent typography, a configurable sidebar, powerful search (Pagefind), accessibility features, dark/light mode switching, and an easy path to a customized homepage. It outputs static HTML perfectly suited for GitHub Pages.
+- **Styling**: Tailwind CSS (to be added) for the homepage custom layout and utility classes, with customized Starlight CSS variables for the NMSh identity (Lavender accent: `#A67CF3`).
+
+## 2. Content Architecture
+The site is organized into logical learning paths to support both beginners and experienced users without overwhelming navigation.
+
+- **Learn (Getting Started)**: Intro, Installation, First Launch, Basic Walkthrough.
+- **Guides**:
+ - Fundamental Concepts (ShellAdapter, PTYs, UI boundaries)
+ - Composer and Interaction
+ - Transcripts and Workflows
+ - Appearance and Customization (Theme Studio, Theme Bridge)
+ - Sessions and Workspaces
+ - Context Engine and Modules (Extensive coverage of v0.17 foundation and planned v0.19 features)
+ - Tool Integrations (fzf, zoxide, starship, dotfiles)
+ - Managed Agents (Claude)
+- **Reference**:
+ - Commands and Keyboard Shortcuts
+ - Configuration files
+ - Theme JSON format
+ - Context Pack format
+- **Project**:
+ - Architecture
+ - Roadmap & Releases (Clear demarcation of v0.17 released vs v0.18/0.19 dev)
+
+## 3. Feature/Status Inventory Strategy
+To clearly distinguish released vs in-development features, we will use custom Starlight `Badge` components or a reusable MDX `` component.
+- **Released (v0.17.0)**: Documented normally.
+- **Implemented, Unreleased (dev/v0.18.0/v0.19.0)**: Documented with clear "Unreleased" badges and notes that these features require building from the `dev` branch or wait for the next release.
+- **Planned**: Mentioned in the Roadmap section, not mixed into active tutorials.
+
+## 4. Build and Deployment
+- **Local Dev**: `npm run dev` in the `site/` directory.
+- **Build**: `npm run build` in the `site/` directory.
+- **Deployment**: A GitHub Actions workflow `.github/workflows/deploy.yml` triggers on pushes to `docs/github-pages-site`. It builds the Astro site and deploys the static output to GitHub Pages.
+
+## 5. Media Integration (Future)
+We have intentionally excluded existing screenshots and GIFs as requested.
+- **How to add media later**:
+ - Place WebP images or MP4/WebM videos in `site/src/assets/`.
+ - Use Astro's `` component or standard HTML `