docs: Official documentation website (Starlight)

.github/workflows/deploy.yml

@@ -0,0 +1,77 @@
+name: Deploy Documentation Site to GitHub Pages
+
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  BUILD_PATH: "./site"
+
+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

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

site/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

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"
+    }
+  ]
+}

site/DEVELOPMENT.md

@@ -0,0 +1,39 @@
+# NMSh Website Development Record
+
+## 1. Stack and Architecture
+- **Framework**: Astro with Starlight.
+- **Why**: Starlight provides out-of-the-box support for Markdown/MDX, typography, a configurable sidebar, Pagefind search, accessibility features, dark/light mode switching, and static HTML output for GitHub Pages.
+- **Styling**: Tailwind CSS (v4) for utility classes, with customized Starlight CSS variables for the NMSh identity (Lavender accent: `#ac96e6`).
+
+## 2. Content Architecture
+The site is organized into logical learning paths to support both beginners and experienced users without overwhelming navigation.
+
+- **Learn**: What is NMSh, Fundamental Concepts (ShellAdapter, PTYs, UI boundaries).
+- **Guides**: Composer, Transcripts, Customization, Context Engine, Sessions, Tools, Agents, Troubleshooting, Contributing.
+- **Reference**: Comprehensive CLI Commands & Flags, Configuration files, Keyboard Shortcuts matrix.
+- **Project**: Architecture, Roadmap & Releases.
+
+## 3. Feature/Status Provenance Strategy
+To clearly distinguish released vs in-development features, we use a reusable MDX `<Availability />` component supporting dynamic version and branch properties.
+- **Released**: `status="released" version="v0.17.0"`
+- **Unreleased (v0.18.0)**: `status="unreleased" version="v0.18.0" pr="345" issue="305"` (Implemented on `release/v0.18.0` integration branch, slated for v0.18.0 release)
+- **In Progress**: `status="in-progress" issue="358"`
+- **Planned**: `status="planned" version="v0.19.0"`
+
+## 4. Branding and Assets
+- Strictly no legacy screenshots, GIFs, stock imagery, or placeholder artwork.
+- We exclusively use official vector branding: `nmsh-lockup.svg`, `vespyr-divider.svg`, and architectural diagrams (`architecture.svg`, `architecture-detailed.svg`).
+- Future media should be captured at 16:9 or terminal standard ratios, saved as WebP, and placed in `src/assets/`.
+
+## 5. Build and Deployment
+- **Local Dev**: `npm install` then `npm run dev` in the `site/` directory.
+- **Build**: `npm run build` inside `site/`.
+- **Deployment Workflow**: `.github/workflows/deploy.yml` triggers on pushes to `master` and manual `workflow_dispatch`.
+
+## 6. Completed Source-Backed Audit
+- **Configuration Paths**: Corrected paths per `src/configuration/paths.ts`: macOS (`~/Library/Application Support/notMyShell/config.json`) and Linux (`~/.config/nmsh/config.json` or `$XDG_CONFIG_HOME/nmsh/config.json`).
+- **Portable Categories**: Updated export categories to match the 18 real IDs defined in `src/configuration/portability.ts` (`prompt`, `theme`, `themeBridge`, `chroma`, `chrome`, `syntax`, `transcript`, `layout`, `suggestions`, `providers`, `statusStrip`, `idle`, `notifications`, `tools`, `sessions`, `agents`, `shell`, `editor`).
+- **Context Engine Modules**: Aligned the catalog with the 7 bundled first-party pack definitions in `src/context/packs/builtin/` (`nmsh.agents`, `nmsh.cloud`, `nmsh.environment`, `nmsh.infrastructure`, `nmsh.project`, `nmsh.system`, `nmsh.vcs`). Correctly distinguished core built-in prompt modules (`kubeContext`, `dockerContext`, `cwd`, `gitBranch`, `gitStatus`, etc.) from pack modules.
+- **Commands & Flags**: Verified CLI flags (`nmsh --new`, `--sessions`, `--attach`, `--presets`, `--preset`, `--version`), maintenance commands (`nmsh doctor`, `nmsh uninstall`, `nmsh packs`, `nmsh agent-status`), and all slash commands in `src/commands/slashCommands.ts`.
+- **Keyboard Shortcuts**: Verified key bindings against `src/terminal/keys.ts` and `src/input/editingKeys.ts`.
+- **Authorship Conventions**: Strictly audited all site files, documentation, and commits to ensure zero model/tool attribution references.

site/README.md

@@ -0,0 +1,36 @@
+# notMyShell Documentation Website
+
+Official documentation site for [notMyShell (NMSh)](https://github.com/raiseCatError/notMyShell).
+
+Built with [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
+
+## Development
+
+Run all commands from within the `site/` directory:
+
+```bash
+npm install     # Install dependencies
+npm run dev     # Start local development server (http://localhost:4321)
+npm run build   # Build production static bundle to ./dist/
+npm run preview # Preview the production build locally
+```
+
+## Structure
+
+```
+site/
+├── public/         # Static assets served at the site root
+├── src/
+│   ├── assets/     # Vector branding and diagrams
+│   ├── components/ # Reusable MDX components (<Availability />, etc.)
+│   ├── content/
+│   │   └── docs/   # Documentation pages (MDX)
+│   ├── styles/     # Tailwind and Starlight theme styling
+│   └── custom.css  # Lavender theme styling overrides
+├── astro.config.mjs # Astro and Starlight configuration
+└── package.json
+```
+
+## Deployment
+
+The documentation site deploys to GitHub Pages via `.github/workflows/deploy.yml` on pushes to the `master` branch.

site/astro.config.mjs

@@ -0,0 +1,61 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  site: 'https://raisecaterror.github.io',
+  base: '/notMyShell',
+  integrations: [
+      starlight({
+          title: 'notMyShell',
+          customCss: [
+              './src/styles/global.css',
+              './src/custom.css',
+          ],
+          logo: {
+              src: './src/assets/nmsh-lockup.svg',
+          },
+          sidebar: [
+              {
+                  label: 'Learn',
+                  items: [
+                      { label: 'What is NMSh?', slug: 'guides/getting-started' },
+                      { label: 'Fundamental Concepts', slug: 'guides/concepts' },
+                  ],
+              },
+              {
+                  label: 'Guides',
+                  items: [
+                      { label: 'Composer and Interaction', slug: 'guides/composer' },
+                      { label: 'Transcripts and Workflows', slug: 'guides/transcripts' },
+                      { label: 'Themes and Customization', slug: 'guides/customization' },
+                      { label: 'Context Engine', slug: 'guides/context-engine' },
+                      { label: 'Sessions and Workspaces', slug: 'guides/sessions' },
+                      { label: 'Tool Integrations', slug: 'guides/tools' },
+                      { label: 'Managed Agents', slug: 'guides/agents' },
+                  ],
+              },
+              {
+                  label: 'Reference',
+                  items: [
+                      { label: 'Commands & Flags', slug: 'reference/commands' },
+                      { label: 'Configuration', slug: 'reference/configuration' },
+                      { label: 'Keyboard Shortcuts', slug: 'reference/keyboard-shortcuts' },
+                  ],
+              },
+              {
+                  label: 'Project',
+                  items: [
+                      { label: 'Architecture', slug: 'project/architecture' },
+                      { label: 'Roadmap & Releases', slug: 'project/roadmap' },
+                      { label: 'Troubleshooting', slug: 'guides/troubleshooting' },
+                      { label: 'Contributing', slug: 'guides/contributing' },
+                  ],
+              },
+          ],
+      }),
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});