+
+ {statusLabel()}
+
+
+ {status === 'released' && version && `Available in stable release ${version}.`}
+ {status === 'unreleased' && (version ? `Implemented on the development line and slated for release in ${version}.` : branch ? `Implemented on ${branch}.` : `Implemented on the development branch, not yet published in a stable release.`)}
+ {status === 'in-progress' && `This feature is currently in active development.`}
+ {status === 'planned' && (version ? `This feature is planned for milestone ${version}.` : `This feature is planned for a future release.`)}
+
+ {pr && (
+
+ PR #{pr}
+
+ )}
+ {issue && (
+
+ Issue #{issue}
+
+ )}
+
diff --git a/site/src/content.config.ts b/site/src/content.config.ts
new file mode 100644
index 00000000..d9ee8c9d
--- /dev/null
+++ b/site/src/content.config.ts
@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+ docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/site/src/content/docs/guides/agents.mdx b/site/src/content/docs/guides/agents.mdx
new file mode 100644
index 00000000..b2120fd3
--- /dev/null
+++ b/site/src/content/docs/guides/agents.mdx
@@ -0,0 +1,34 @@
+---
+title: Managed Agents
+description: Using AI agents and local models within NMSh.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+While NMSh is **not an AI-first terminal**, it offers powerful integrations with managed coding agents for those who want them. These integrations are completely optional and do not phone home by default.
+
+## Local Guidance (`/btw` / `/ask`)
+
+NMSh provides a built-in assistant to help you navigate its commands and settings.
+
+- Type `/btw` (or `/ask`) followed by a question to get local guidance mapped to typed NMSh actions.
+- By default, this uses a deterministic local engine.
+- You can opt-in to using a local model (Qwen Local Understanding) through `/llm`. **Models are never downloaded without explicit Yes confirmation.**
+
+## Claude Code Agent Context
+
+
+
+If you use Claude Code, NMSh can display its session context in your prompt or Context Rail.
+
+NMSh uses Claude Code's official status-line interface, **never terminal scraping**.
+
+To set it up:
+1. Run `nmsh agent-status setup`. This shows the exact change to Claude Code's `settings.json`.
+2. Apply the change.
+3. NMSh will keep an allowlisted, private record per NMSh session.
+4. Modules can now show model, effort, context-window use, and 5-hour/7-day limits.
+
+> **Privacy:** Prompts, transcripts, and terminal output are never read by NMSh's agent status bridge. The data is display-only and is not kept in history.
diff --git a/site/src/content/docs/guides/composer.mdx b/site/src/content/docs/guides/composer.mdx
new file mode 100644
index 00000000..5b1e3204
--- /dev/null
+++ b/site/src/content/docs/guides/composer.mdx
@@ -0,0 +1,41 @@
+---
+title: Composer and Interaction
+description: Using the NMSh composer, completion, and keyboard shortcuts.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+The **composer** is the persistent editor at the bottom (or top) of your NMSh window where you type commands. It provides multiline editing, semantic syntax highlighting, and intelligent suggestions before a command is executed.
+
+## Composer Layouts
+
+You can position the composer via **Config → Composer position**:
+- **Bottom**: The classic layout. Input stays at the bottom of the screen.
+- **Top**: Input sits at the top; output pushes down.
+- **Flow**: The composer naturally follows the newest output, similar to a traditional terminal.
+
+You can also use a **two-line** layout where your prompt sits above the input line, or a **one-line** layout.
+
+## Semantic Highlighting
+
+As you type, NMSh tokenizes and highlights your command based on real shell knowledge. Commands, builtins, aliases, and functions are recognized. Partial input is **never executed** behind the scenes.
+
+## Predictive Suggestions (NMSh Native)
+
+Ghost text suggestions are ranked by:
+- Fuzzy and acronym matching
+- Frecency
+- The current directory
+- What usually follows the previous command
+
+**Navigation:**
+- `Right Arrow` or `End` accepts the full suggestion.
+- `Alt + Right Arrow` accepts the next word.
+- `Ctrl + N` / `Ctrl + P` lists ranked alternatives.
+- `Esc` dismisses the suggestion.
+
+## The Command Palette
+
+Press `F1`, `Ctrl+Shift+P`, `Cmd+Shift+P`, or type `/palette` to open the Command Palette. It allows you to search through NMSh slash-commands, settings, layout toggles, and themes without executing shell text.
diff --git a/site/src/content/docs/guides/concepts.mdx b/site/src/content/docs/guides/concepts.mdx
new file mode 100644
index 00000000..89a84f1b
--- /dev/null
+++ b/site/src/content/docs/guides/concepts.mdx
@@ -0,0 +1,39 @@
+---
+title: Fundamental Concepts
+description: Core architectural concepts of notMyShell.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+## What NMSh is (and is not)
+
+NMSh is a **frontend**. Your shell stays underneath and does what it always did: parsing, execution, aliases, functions, environment, and job control.
+
+NMSh owns what you see and type: the composer and editor, completion and suggestions, history and transcript, prompt and layout, sessions, themes and Chroma, tool panels, and local guidance.
+
+- **Not a shell.** It does not reimplement zsh, Bash or Fish; it runs them.
+- **Not a terminal emulator.** Keep Ghostty, Terminal.app, VS Code, Zed or whatever you use.
+- **Not a prompt theme.** The Native prompt is optional; Starship, Oh My Posh or Powerlevel10k can supply the prompt instead, or none at all.
+- **Not an AI terminal.** NMSh's core experience uses deterministic local logic without cloud inference or model API calls. Integrations are opt-in.
+
+## The ShellAdapter
+
+The ShellAdapter is the boundary between the NMSh frontend and your real shell. It handles the low-level communication with the pseudo-terminal (PTY) where your shell actually lives. NMSh supports:
+- **zsh** (default)
+- **Bash 4.4+**
+- **Fish**
+
+All three run behind a unified ShellAdapter interface. NMSh loads your startup files in a controlled bootstrap and never edits them. ZLE prompt and widget UI (like Powerlevel10k's in-shell prompt or zsh-autosuggestions) is kept off inside NMSh so it cannot fight the composer. They continue to work if you drop into an ordinary shell via `/zsh`.
+
+## Composer vs Transcript
+
+- **The Composer:** The persistent editor where you write commands. It can be docked to the Bottom, Top, or flow naturally after the newest output. It supports full multiline editing and provides semantic syntax highlighting before execution.
+- **The Transcript:** The scrollable record of your past commands and their output. Commands in the transcript are structured blocks with status, timing, and an attached prompt snapshot.
+
+## Passthrough Behavior
+
+Fullscreen and raw interactive terminal applications use the passthrough path. Their input and display remain with the real program. When a fullscreen app takes over, NMSh steps aside, ensuring raw PTY output remains raw and is not semantically recolored by NMSh.
+
+## Sessions and Detachment
+
+NMSh sessions are persistent. Closing a terminal window **detaches** the shell instead of ending it. Running commands continue executing in the background. You can `/resume` them later or attach to them with `nmsh --attach `.
diff --git a/site/src/content/docs/guides/context-engine.mdx b/site/src/content/docs/guides/context-engine.mdx
new file mode 100644
index 00000000..0fa892e2
--- /dev/null
+++ b/site/src/content/docs/guides/context-engine.mdx
@@ -0,0 +1,132 @@
+---
+title: Context Modules and Engine
+description: Native context modules, surface routing, built-in prompt modules, and declarative Context Packs.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh runs around a real persistent zsh, Bash or Fish session. Its native modules present useful context about that session and workspace — the project, Git, runtimes, cloud contexts, the machine, an agent's session — without taking over shell execution or executing workspace scripts.
+
+## Architecture & Data Flow
+
+The Context Engine follows a strict path from demand to presentation:
+
+1. **Capability**: A named operation implemented and audited in NMSh core (e.g. reading nearest package manifest, checking battery charge).
+2. **Fact**: One resolved value with its source, freshness, trust level, sensitivity, and persistence policy.
+3. **Module**: A presentation definition that reads facts and formats segments.
+4. **Surface Router**: Places the module on the appropriate UI surface based on screen width and user preference.
+5. **Surfaces**: Main Prompt, Right Context, Context Rail, or Status Strip.
+
+## Surfaces
+
+NMSh routes context to four distinct surfaces configured via `/prompt`:
+
+- **Main Prompt**: Stable identity and navigation context anchored to your composer (directory, project, Git branch).
+- **Right Context**: Independently anchored context at the right margin of the prompt row.
+- **Context Rail**: Dynamic contextual modules attached directly above or below the composer, appearing conditionally (e.g. `onCommand`).
+- **Status Strip**: Persistent, low-attention telemetry along the bottom edge of the terminal.
+
+---
+
+## Built-in Prompt Modules
+
+NMSh core includes purpose-built prompt modules with specialized renderers:
+
+| Module ID | Label | Description | Default Surface |
+|---|---|---|---|
+| `project` | Project | Repository or directory name. | Main Prompt |
+| `cwd` | Path | Working directory path, intelligently shortened to fit geometry. | Main Prompt |
+| `gitBranch` | Git Branch | Current Git branch or detached HEAD commit. | Main Prompt |
+| `gitStatus` | Git Status | Rich Git working-tree status (staged, unstaged, untracked, ahead/behind). | Main Prompt |
+| `toolchain` | Toolchains | Toolchains whose marker files exist in this project. | Main Prompt |
+| `exitStatus` | Exit Status | Exit code of the last executed command (shows on failure by default). | Main Prompt |
+| `kubeContext` | Kubernetes | Active kubeconfig context and namespace (appears on `kubectl`, `helm`). | Context Rail |
+| `dockerContext`| Docker Context| Active Docker CLI context (appears on `docker`, `docker-compose`). | Context Rail |
+| `shell` | Current Shell | Displays the backend shell when it differs from your default backend. | Right Context |
+| `discoveredTools`| Local Tools | Count of local CLI tools detected in your environment. | Right Context |
+
+---
+
+## Declarative Context Packs
+
+
+
+Additional modules are provided through bundled and installed **Context Packs**.
+
+**Packs are purely declarative data, not plugins.** A pack is a validated JSON manifest that names capabilities NMSh core implements and describes how to render them. A pack **cannot** contain or reference shell commands, scripts, argv, templates, executable hooks, or network URLs.
+
+### Managing Packs
+
+Packs are managed via the `nmsh packs` CLI:
+
+```bash
+nmsh packs # List bundled and installed packs
+nmsh packs inspect FILE # Validate a pack file and review what it reads
+nmsh packs install FILE [--sha256] # Install pack (modules start hidden until enabled in /prompt)
+nmsh packs enable ID | disable ID # Enable or disable an installed pack
+nmsh packs remove ID # Remove an installed pack and its module entries
+```
+
+---
+
+## First-Party Bundled Pack Catalog
+
+NMSh ships with 7 first-party Context Packs defined in `src/context/packs/builtin/`:
+
+### 1. `nmsh.project` — Package & Language Runtimes
+Extracts version and runtime details using bounded, local file reads:
+- `package`: Name and version from nearest manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, etc.). (Surface: Right Context)
+- `node`: Node.js active/requested version from `.nvmrc` or `.node-version`. (Triggers: `node`, `npm`, `pnpm`, `yarn`, `bun`; Surface: Context Rail)
+- `python`: Python version, active virtualenv, and package manager. (Triggers: `python`, `pip`, `uv`, `pytest`; Surface: Context Rail)
+- `go`: Go version from `go.mod` or `go.work`. (Triggers: `go`; Surface: Context Rail)
+- `rust`: Active or requested `rustup` toolchain. (Triggers: `cargo`, `rustc`; Surface: Context Rail)
+- `java`: JDK version from release file and build tool (Maven/Gradle). (Triggers: `java`, `mvn`, `gradle`; Surface: Context Rail)
+
+### 2. `nmsh.cloud` — Cloud Providers
+Reads non-secret local CLI configuration files. **Makes zero network requests, zero API calls, and handles no secrets**:
+- `aws`: Active AWS profile, region, and local credential expiry. (Triggers: `aws`, `sam`, `cdk`, `terraform`; Surface: Context Rail)
+- `gcp`: Active Google Cloud project/configuration and region. (Triggers: `gcloud`, `bq`, `terraform`; Surface: Context Rail)
+- `azure`: Active Azure CLI subscription. (Triggers: `az`, `func`, `terraform`; Surface: Context Rail)
+
+### 3. `nmsh.infrastructure` — Infrastructure as Code
+Inspects local workspace configuration files:
+- `terraform`: Active Terraform or OpenTofu workspace. (Triggers: `terraform`, `tofu`, `terragrunt`; Surface: Context Rail)
+- `helm`: Chart name and version from nearest `Chart.yaml`. (Triggers: `helm`, `helmfile`; Surface: Context Rail)
+- `pulumi`: Selected Pulumi stack or project from `Pulumi.yaml`. (Triggers: `pulumi`; Surface: Context Rail)
+
+### 4. `nmsh.environment` — Environment Managers & Direnv
+Reads declarative environment manager requests:
+- `tools`: Requested tool versions from `.tool-versions` or `mise.toml` (never executes `asdf` or `mise`). (Surface: Right Context)
+- `direnv`: Indicates whether direnv loaded this workspace's `.envrc` (never reads or sources `.envrc`). (Surface: Right Context)
+
+### 5. `nmsh.system` — System & Session Metrics
+Reads local OS metrics using bounded system APIs:
+- `os`: Operating system name and version. (Surface: Right Context)
+- `user`: Displays `user@host` during SSH sessions, and a prominent warning when running as `root`. (Surface: Main Prompt)
+- `jobs`: Number of background and stopped shell jobs. (Surface: Right Context)
+- `duration`: Elapsed time for the current NMSh session. (Surface: Right Context)
+- `time`: Current local clock. (Surface: Right Context)
+- `battery`: Battery charge level and charging indicator. (Surface: Right Context)
+- `memory`: Memory utilization percentage. (Surface: Right Context)
+
+### 6. `nmsh.vcs` — Git Extras
+Supplements core Rich Git with repository metadata:
+- `stash`: Number of stashed changes in the current Git repository. (Surface: Right Context)
+- `upstream`: Configured Git upstream tracking branch. (Surface: Right Context)
+
+### 7. `nmsh.agents` — Agent Session Context
+Provides integration for coding assistants:
+- `claude`: Claude Code active model, reasoning effort, token usage, and session cost. (Triggers: `claude`; Surface: Context Rail)
+- `claude-limits`: Claude Code 5-hour and 7-day rate limit consumption and reset countdowns. (Surface: Context Rail)
+
+---
+
+## Security Boundaries
+
+**Entering a repository never executes repository code, invokes untrusted executables, or contacts the network for context discovery:**
+
+- **No Code Execution**: Executables discovered on `PATH` are evidence of tooling, not permission to execute them.
+- **Bounded Metadata Reads**: Manifest reads enforce strict size limits and refuse leaf symlinks and non-regular files.
+- **Trusted Git Only**: The VCS collector executes trusted system `git` with hooks (`core.hooksPath=/dev/null`) and filesystem monitors explicitly disabled.
diff --git a/site/src/content/docs/guides/contributing.mdx b/site/src/content/docs/guides/contributing.mdx
new file mode 100644
index 00000000..c7638daa
--- /dev/null
+++ b/site/src/content/docs/guides/contributing.mdx
@@ -0,0 +1,70 @@
+---
+title: Contributing
+description: Guidelines for developing notMyShell and maintaining the documentation.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+Thank you for your interest in improving notMyShell. NMSh is an open-source terminal frontend, and development happens entirely on GitHub.
+
+## Project Structure
+
+- `src/`: The core TypeScript application (UI, PTY orchestration, semantic parser, configuration).
+- `site/`: The Astro/Starlight documentation website (where you are now).
+- `tests/`: Automated test suite asserting correctness and observability.
+- `assets/`: Official branding, vectors, and design lockups.
+- `docs/`: In-repository architecture and design decision records.
+
+## Branching Strategy
+
+- **`master`**: The stable branch, representing the latest released version of NMSh. Do not commit here unless resolving a critical hotfix for a stable release.
+- **`dev`**: The active development branch. All feature PRs and bug fixes must target `dev`.
+- **Feature Branches**: Should be created off `dev` and cleanly merge back into it.
+
+## Development Loop
+
+To work on NMSh locally:
+
+1. Clone the repository and checkout `dev`.
+2. Run `npm ci` to install dependencies.
+3. Build the core application: `npm run build`.
+4. Launch your local build in development mode using `npm run start` or `./bin/nmsh`.
+
+### Verification & Testing
+
+Do not hardcode test totals in documentation, as they change with every merge.
+
+- `npm run verify:fast`: Runs the build, a focused test subset, and diff checks. Ideal for rapid iteration.
+- `npm run verify`: Runs the full canonical test suite and linter. **Must pass before pushing.**
+- `npm run verify:release`: Includes benchmark script typechecking and bounded timing smoke tests. Used for release qualification.
+
+### Physical Terminal Validation
+
+"All tests passed" is not equivalent to "human terminal validation passed." Features involving visual geometry, PTY resizing, keyboard protocols (e.g., Kitty `CSI u`), or system integration must be physically verified in terminal hosts (Ghostty, Terminal.app, iTerm2, etc.) before closure.
+
+## Documentation Website
+
+The documentation website lives in the `site/` directory and is built with Astro and Starlight.
+
+- **No existing screenshots**: Do not embed legacy screenshots or generated AI UI mockups. Use only official vector branding (`assets/brand/nmsh-lockup.svg`, `assets/readme/vespyr-divider.svg`).
+- **Feature Provenance**: Use the `` component to distinctly mark features that are `released`, `unreleased` (on the dev branch), `in-progress`, or `planned`.
+- **Local Docs Dev**:
+ ```bash
+ cd site
+ npm install
+ npm run dev
+ ```
+
+## Automated Contribution Guidelines
+
+When running automated development tools or contributor workflows:
+- **Read `AGENTS.md`** first. It contains standing authorization, strict constraints on project boards, and workflow rules.
+- Do not commit directly to `master`.
+- Do not falsely claim human validation has occurred. Leave issues requiring manual terminal verification open with a "Needs Human Test" label.
+- Commits, pull requests, and documentation must carry no model attribution, tool signatures, or co-author trailers.
+
+## Issue Tracking
+
+GitHub is the durable source of truth. Refer to the [GitHub Issues](https://github.com/raiseCatError/notMyShell/issues) and the [ROADMAP](https://github.com/raiseCatError/notMyShell/blob/master/ROADMAP.md) before starting new work.
diff --git a/site/src/content/docs/guides/customization.mdx b/site/src/content/docs/guides/customization.mdx
new file mode 100644
index 00000000..d4e9a3b7
--- /dev/null
+++ b/site/src/content/docs/guides/customization.mdx
@@ -0,0 +1,64 @@
+---
+title: Themes and Customization
+description: How to customize NMSh appearance, Theme Studio, and Theme Bridge.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh is highly customizable, allowing you to tailor the prompt, colors, cursor, and more to your liking.
+
+## Theme Studio (`/theme`)
+
+The Theme Studio is your central hub for managing your palette. It contains tabs for:
+
+- **Built-in**: The standard themes shipped with NMSh (e.g., Lavender Native).
+- **Imported**: Themes imported from other formats.
+- **Custom**: Themes you have edited or created.
+- **Import**: Tools to bring in themes from external sources.
+
+You can preview any theme live against synthetic prompt data before applying it.
+
+### Imports
+
+NMSh supports importing colors (data only) from a wide variety of formats:
+
+- NMSh Theme JSON
+- Base16 / Base24
+- Windows Terminal
+- Oh My Posh (JSON, YAML, TOML)
+- Kitty
+- Ghostty (allowlist)
+- iTerm2 (`.itermcolors`)
+- WezTerm (TOML only, Lua is refused)
+
+## Theme Bridge (`/theme-bridge`)
+
+Theme Bridge extends your active NMSh theme to external tools. It is **opt-in** and strictly uses data configurations without sourcing arbitrary shell scripts.
+
+You can apply themes **Manually** (per tool) or **Follow NMSh** globally.
+
+Supported targets:
+- `fzf`
+- `less` / `man`
+- File listing colors (GNU `ls` with `vivid`, or BSD `ls` with `LSCOLORS`)
+- `tmux`
+- `Neovim`
+- `Vim`
+- `Helix`
+- `bat`
+
+> **Note on `delta`:** NMSh never manages `delta` directly (it does not modify git config). However, once `bat` is configured to follow NMSh, `delta` will automatically inherit the syntax highlighting colors.
+
+## Appearance Panel (`/appearance`)
+
+The `/appearance` command acts as a compact launcher for all visual settings:
+- Theme Studio
+- Prompt configuration
+- Cursor & effects
+- UI chrome
+- Chroma (color treatments)
+- Motion
+- Theme Bridge
+- Host window configuration
diff --git a/site/src/content/docs/guides/getting-started.mdx b/site/src/content/docs/guides/getting-started.mdx
new file mode 100644
index 00000000..f0c507ba
--- /dev/null
+++ b/site/src/content/docs/guides/getting-started.mdx
@@ -0,0 +1,57 @@
+---
+title: Getting Started
+description: How to install and set up notMyShell on macOS, Linux, and WSL.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+notMyShell (NMSh) is a terminal frontend that operates over a persistent, real shell session (zsh, Bash, or Fish). Instead of replacing the shell or running commands as isolated subprocesses, NMSh orchestrates a hidden pseudo-terminal (PTY) running that shell.
+
+## Installation
+
+### Homebrew (macOS)
+
+Homebrew is the recommended install method on macOS.
+
+```sh
+brew install raiseCatError/tap/nmsh
+nmsh
+```
+
+To update, use `brew upgrade raiseCatError/tap/nmsh`.
+
+### Build from source (macOS, Linux, WSL 2)
+
+You need:
+- Node.js 22 or newer
+- zsh (default), Bash 4.4+, or Fish
+
+```sh
+git clone https://github.com/raiseCatError/notMyShell.git
+cd notMyShell
+npm install
+npm run build
+npm link
+nmsh
+```
+
+> **Note on GUI terminals:** To start NMSh from a GUI terminal like Ghostty or Zed, use absolute paths so macOS `PATH` differences cannot break startup: `command = direct:/absolute/path/to/node /absolute/path/to/nmsh`.
+> **Never** set `nmsh` as your system/login shell with `chsh`.
+
+## First Launch
+
+When you first run `nmsh`, you will be greeted by **Setup Cat**. Setup Cat guides you through the initial customization, including choosing a layout (Bottom, Top, or Flow), a prompt style, and a theme.
+
+If you skip setup or want to change it later, type `/setup` in the composer.
+
+## Switching Shells
+
+NMSh uses a shared ShellAdapter for zsh, Bash, and Fish. To switch the shell of your *current session*, type:
+
+```sh
+/shell
+```
+
+To set the default shell for *new sessions*, go to `/settings` and navigate to the Sessions tab.
diff --git a/site/src/content/docs/guides/sessions.mdx b/site/src/content/docs/guides/sessions.mdx
new file mode 100644
index 00000000..9050b03a
--- /dev/null
+++ b/site/src/content/docs/guides/sessions.mdx
@@ -0,0 +1,29 @@
+---
+title: Sessions and Workspaces
+description: How NMSh handles persistent live sessions.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh sessions are built to survive window closures, network drops, and terminal emulator crashes.
+
+## Persistent Live Sessions
+
+Under the hood, NMSh runs your shell in a small background service (`nmshd`). When you close a terminal window, the shell **detaches** instead of dying.
+
+If a command is running (e.g., a build script, a dev server, or a long copy), it continues executing.
+
+## Reattaching
+
+When you open a new terminal window, NMSh's startup prompt allows you to choose an existing live session to reattach to, or start a new one.
+
+- `/resume`: Opens the session viewer. **LIVE** sessions are listed at the top, above **ARCHIVED** transcripts. You can see what each live session is doing (the running command, elapsed time, etc.).
+- `nmsh --attach `: Attach directly from the command line.
+
+When you reattach, any output that was printed while the session was detached is safely spooled and appended to your transcript.
+
+## Interactive UIs and Handoff
+
+If a detached session was running an interactive UI (like an editor, Claude Code, or a pager), NMSh correctly restores the terminal modes (including mouse reporting and bracketed paste) when you reattach, handing control back to the application seamlessly.
diff --git a/site/src/content/docs/guides/tools.mdx b/site/src/content/docs/guides/tools.mdx
new file mode 100644
index 00000000..ee3657d2
--- /dev/null
+++ b/site/src/content/docs/guides/tools.mdx
@@ -0,0 +1,40 @@
+---
+title: Tool Integrations
+description: Using /tools, /providers, and shell frameworks safely with NMSh.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh integrates with a curated list of shell tools and frameworks, explicitly detecting them and offering configuration options without silently modifying your shell initialization files.
+
+## The Tool Browser (`/tools`)
+
+Type `/tools` to open the Tool Browser. This panel shows a curated catalog of shell tools.
+
+- **Relevant here**: Suggests tools based on local evidence (e.g., suggesting Go if a `go.mod` is found).
+- **Bulk install**: Select multiple missing tools with `Space`, then press `Enter` to review a bulk install plan using your system's package manager.
+- **Safety**: Installs use explicit `sudo -n` for operations requiring privileges. Nothing elevates silently.
+
+## Providers (`/providers`)
+
+The Provider framework allows you to select which backend powers certain NMSh features.
+
+- **Prompt**: NMSh Native (default), Starship, Oh My Posh, or Powerlevel10k.
+- **Welcome**: Vespyr (default), Fastfetch, Neofetch, or None.
+- **Suggestions / Navigation / History**: Upcoming integrations for fzf, Atuin, zoxide, Television, etc.
+
+## Shell Frameworks
+
+NMSh respects your shell frameworks but treats them differently than prompt engines.
+
+- **Oh My Zsh**: Detected automatically. NMSh provides a guided install that keeps your `.zshrc` safe, offering to backup and restore `.zshrc.pre-oh-my-zsh` upon confirmation. It never runs the official installer silently.
+- **Prezto, Zim, zinit, Antidote**: Detected and shown as inspect-only.
+
+## Tool Configuration (`/configure`, `/tmux`, `/dotfiles`)
+
+NMSh can safely configure certain tools for you.
+
+- **`/tmux`**: Opens the tmux Config Studio. Customize settings, keymaps, and the status bar. Changes are saved to a single NMSh-managed file and included in your `.tmux.conf` only after your review.
+- **`/dotfiles [path]`**: Import settings from plain, Git, or GNU Stow sources. Repositories are cloned (depth 1) only after confirmation. Nothing is run, templates are not rendered, and all executable configs are inspect-only.
diff --git a/site/src/content/docs/guides/transcripts.mdx b/site/src/content/docs/guides/transcripts.mdx
new file mode 100644
index 00000000..7d62316b
--- /dev/null
+++ b/site/src/content/docs/guides/transcripts.mdx
@@ -0,0 +1,47 @@
+---
+title: Transcripts and Workflows
+description: Understanding NMSh command transcripts, output folding, and selection.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+The transcript is the scrollable record of your past commands and their output. NMSh structures this output to make it more readable and useful.
+
+## Structured Command Blocks
+
+Each command in the transcript is a discrete block. It contains:
+- The command you typed.
+- The prompt snapshot at the time of execution.
+- The output of the command.
+- Status (success or failure) and execution timing.
+
+## Output Folding
+
+Configured via **Config → Output folding** (Smart, Always, or Never).
+
+- **Smart** (Default): Folds long, low-information output (like build chatter or progress rewrites) but keeps errors, diagnostics, diffs, and failures expanded.
+- **Always**: Folds all long blocks, keeping only the head and tail visible.
+- **Never**: Disables folding.
+
+A folded block displays a summary like `› N lines hidden · Ctrl+O` and can be expanded at any time.
+
+## Search and Filtering
+
+You can search and filter the transcript to find past output quickly:
+
+- `/find`: Search the transcript for specific text.
+- `/filter`: Filter the transcript to show only matching lines. This is presentation only; the underlying stored output is unchanged.
+
+## Copy Workflows
+
+Because NMSh manages the output, copying text from the transcript is clean. Terminal escape sequences, bidi formatting, and NMSh UI chrome are stripped out, giving you pure text.
+
+
+
+**Copy Selection and Copy Modes:** Enhanced copy workflows (including plain-text `/copy`) and Smart Folding refinements are currently in development.
+
+## Sticky Headers
+
+While scrolling through long output, the command that generated the output stays pinned as a one-row header at the top of the viewport. Clicking it jumps you back to the real header.
diff --git a/site/src/content/docs/guides/troubleshooting.mdx b/site/src/content/docs/guides/troubleshooting.mdx
new file mode 100644
index 00000000..187bc857
--- /dev/null
+++ b/site/src/content/docs/guides/troubleshooting.mdx
@@ -0,0 +1,66 @@
+---
+title: Platform Troubleshooting
+description: Solutions for common NMSh issues across macOS, Linux, WSL 2, and various terminal hosts.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+notMyShell interacts closely with your OS, PTY, and terminal emulator. This guide covers common edge cases and platform-specific resolutions.
+
+## Terminal Hosts
+
+NMSh runs *inside* your terminal emulator. It requires a host with standard VT sequence support.
+
+### Ghostty & Kitty
+**Status: Excellent.**
+These terminals support the Kitty Keyboard Protocol natively. NMSh will automatically negotiate `CSI > 1 u` flags to receive unambiguous modifier keys (e.g., distinguishing `Shift+Enter` from standard `Enter`).
+- **Issue**: Themes mismatch.
+- **Fix**: Use `/theme` and ensure Theme Bridge is enabled to synchronize NMSh's internal palette with your host.
+
+### macOS Terminal.app & iTerm2
+**Status: Fully Supported.**
+- **Issue (Word navigation/deletion fails)**: Pressing `Option+Left` or `Option+Backspace` prints characters (like `[D` or `∫`) instead of navigating or deleting words.
+- **Fix (Terminal.app)**: Go to Terminal > Settings > Profiles > Keyboard. Check **"Use Option as Meta key"**.
+- **Fix (iTerm2)**: Go to Settings > Profiles > Keys. Set Left/Right Option Key to **"Esc+"**.
+
+### Zed
+**Status: Supported (Integrated Terminal).**
+- **Issue**: Complex keyboard shortcuts (like `Cmd+Up`) are intercepted by the editor rather than passed to NMSh.
+- **Fix**: Use standard fallback editing keys (`Alt+f`, `Alt+b`, `Ctrl+k`) which are universally passed through to the PTY.
+
+### WezTerm
+**Status: Supported.**
+- **Issue**: Ligatures or special glyphs are cut off in the powerline prompt.
+- **Fix**: Ensure your font supports powerline glyphs (e.g., Nerd Fonts), and check your WezTerm config for `custom_block_glyphs = true`.
+
+## macOS
+
+### Homebrew PATH Issues
+- **Issue**: `nmsh` is installed via Homebrew (`brew install raiseCatError/tap/nmsh`), but the command is not found.
+- **Fix**: Ensure `/opt/homebrew/bin` (Apple Silicon) or `/usr/local/bin` (Intel) is correctly exported in your `~/.zshrc` or `~/.bash_profile`.
+
+### Terminal Title Conflicts
+- **Issue**: The window title flickers or shows raw shell prompts.
+- **Fix**: Disable your shell's internal title injection (e.g., `DISABLE_AUTO_TITLE="true"` in Oh My Zsh) and let NMSh manage the title via `/settings > Terminal Title`.
+
+## Linux
+
+### Keep Awake (Systemd Inhibitor)
+- **Issue**: Running `/zoomies` or `/caffeinate` on Linux fails to prevent sleep.
+- **Fix**: NMSh's Linux Keep Awake attempts to use the `systemd-inhibit` API. This requires an active D-Bus session and user privileges to request sleep inhibitors. Under Wayland, some compositors (like Sway) have their own idle managers (e.g., `swayidle`). You may need to configure your compositor to respect `systemd-inhibit`.
+
+### Headless Environments & X11
+- **Issue**: Launching NMSh in a pure TTY (no X11/Wayland) or SSH session without proper terminfo.
+- **Fix**: NMSh checks `process.stdin.isTTY` and `process.stdout.isTTY`. Ensure `$TERM` is set to a reasonable fallback (e.g., `xterm-256color`) if `nmsh` complains about terminal support.
+
+## WSL 2 (Windows Subsystem for Linux)
+
+### Windows Terminal Symlinks
+- **Issue**: Importing dotfiles (`/dotfiles`) or reading Context Engine metadata fails on paths shared with the Windows `C:` drive via `/mnt/c/`.
+- **Fix**: NMSh refuses to traverse unsafe filesystem boundaries or follow symlinks that cross into Windows mounts for metadata reads. Keep your active development projects natively inside the WSL 2 ext4 filesystem (`~/`) rather than `/mnt/c/` for full Context Engine support and faster performance.
+
+### Clipboard/Paste Issues
+- **Issue**: Pasting large blocks of text is extremely slow or loses characters.
+- **Fix**: Windows Terminal generally supports Bracketed Paste. Ensure your Windows Terminal is up to date. NMSh intercepts bracketed paste and triggers the `Paste Guard` for safe multiline review.
diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx
new file mode 100644
index 00000000..5db1e336
--- /dev/null
+++ b/site/src/content/docs/index.mdx
@@ -0,0 +1,86 @@
+---
+title: notMyShell
+description: A terminal frontend for your real shell.
+template: splash
+hero:
+ tagline: A focused frontend over your persistent zsh, Bash, and Fish sessions. NMSh owns what you see and type—providing a docked or flowing composer, background semantic classification, a searchable transcript, live command telemetry, and clean shell handoff.
+ image:
+ file: ../../assets/nmsh-lockup.svg
+ alt: notMyShell logo featuring Vespyr
+ actions:
+ - text: Getting Started
+ link: /notMyShell/guides/getting-started/
+ icon: right-arrow
+ variant: primary
+ - text: Architecture
+ link: /notMyShell/project/architecture/
+ icon: open-book
+ - text: GitHub Repository
+ link: https://github.com/raiseCatError/notMyShell
+ icon: external
+ variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+
+
+
+
+## The Terminal Frontend Experience
+
+notMyShell is not a shell, not a terminal emulator, and not an AI assistant. It orchestrates a hidden pseudo-terminal (PTY) running your real interactive shell, presenting a clean, modern interface directly inside your existing terminal emulator (Ghostty, Terminal.app, iTerm2, WezTerm, Alacritty, Kitty).
+
+
+
+ Dock your editor at the **Bottom**, pin it at the **Top**, or let it follow the output in **Flow** mode. Supports true multiline editing (`Shift+Enter`), persistent history, and zero prompt jumping.
+
+
+ Commands, flags, builtins, and paths are tokenized and checked against your live shell environment in the background. Partial input is never blindly executed.
+
+
+ Command execution blocks capture exit status and elapsed runtime. Use `/find` to search output, `/filter` to isolate streams, and `/copy` to extract clean, uncolored plain text.
+
+
+ Closing your terminal window detaches the frontend instead of terminating the shell process. Long-running jobs continue running; reattach effortlessly with `nmsh --attach`.
+
+
+
+---
+
+## Architectural Principles
+
+```
+ +-------------------------------------------------------------+
+ | Terminal Host (Ghostty / Kitty / etc.) |
+ +-------------------------------------------------------------+
+ | Raw PTY Input / VT Escapes
+ v
+ +-------------------------------------------------------------+
+ | NMSh Terminal App Frontend |
+ | - Docked Composer (Flow / Bottom / Top) |
+ | - Semantic Syntax Highlighter (Worker / Lexer) |
+ | - Screen Plan Geometry Engine & Follow/Detached Viewport |
+ +-------------------------------------------------------------+
+ | Targeted PTY Interaction
+ v
+ +-------------------------------------------------------------+
+ | Persistent Shell Session (PTY Daemon) |
+ | zsh | Bash 4.4+ | Fish 3.1+ |
+ +-------------------------------------------------------------+
+```
+
+### 1. Persistent Real Shell State
+NMSh never executes commands by isolated subshell spawning. Environment variables, aliases, shell functions, directory stacks, and history remain intact across commands because the same shell process runs continuously.
+
+### 2. Zero Prompt Contention
+External prompts like Starship, Oh My Posh, and Powerlevel10k run cleanly through NMSh Native context extraction or prompt adapters. Shell UI frameworks (e.g. ZLE, Oh My Zsh) never fight NMSh for terminal ownership.
+
+### 3. Pure Text Integrity
+Raw terminal output from PTY stdout and stderr remains presentation-safe. NMSh never recolors arbitrary output or mangles binary streams. Fullscreen terminal applications (Vim, Less, Htop, Tmux) drop directly into zero-overhead passthrough mode.
+
+---
+
+
+
Free, open source, and built for developers who care about their terminal craft.
+
diff --git a/site/src/content/docs/project/architecture.mdx b/site/src/content/docs/project/architecture.mdx
new file mode 100644
index 00000000..832614ed
--- /dev/null
+++ b/site/src/content/docs/project/architecture.mdx
@@ -0,0 +1,33 @@
+---
+title: Architecture
+description: How notMyShell works end-to-end.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh is a terminal frontend over a persistent real shell session. It intercepts input, provides its own UI for composition and history, and passes execution to a real shell running in a pseudo-terminal (PTY).
+
+## The Runtime Path
+
+1. **Terminal Host**: Your terminal emulator (Ghostty, Terminal.app, WezTerm, etc.) captures keystrokes and renders the cells that NMSh sends it.
+2. **NMSh Frontend**: Owns the composer, transcript, menus, and theming. It parses input for syntax highlighting and suggestions, but **never executes partial input**.
+3. **Session Service (`nmshd`)**: A small background daemon that holds the PTY. This is what allows sessions to detach and reattach.
+4. **ShellAdapter**: The abstraction layer that translates NMSh commands to the specific shell (zsh, Bash, or Fish) and manages shell state safely.
+5. **Real Shell**: The actual `zsh`, `bash`, or `fish` process executing commands.
+
+## Invariants
+
+The NMSh architecture strictly enforces several invariants:
+- **No replacement shell**: NMSh does not reimplement the shell. Job control, parsing, aliases, and environment variables are exactly what your real shell provides.
+- **Raw output remains raw**: PTY output is kept safe. NMSh does not semantically recolor arbitrary PTY output.
+- **Fullscreen Passthrough**: When a program requests the alternate screen or enables mouse reporting (like `vim` or `htop`), NMSh steps completely out of the way.
+- **Safety boundaries**: Theme imports and dotfiles are treated as data, parsed via bounded parsers. Shell config is executable and is never silently modified or sourced.
+
+## Supported Platforms
+
+NMSh is host-independent.
+- **Operating Systems**: macOS (Homebrew/source), Linux (beta), Windows (via WSL 2).
+- **Terminals**: Ghostty and Terminal.app are physically validated. Kitty, iTerm2, WezTerm, and Zed are supported via capability profiles.
+- **Shells**: zsh (default), Bash 4.4+, Fish.
diff --git a/site/src/content/docs/project/roadmap.mdx b/site/src/content/docs/project/roadmap.mdx
new file mode 100644
index 00000000..940393e5
--- /dev/null
+++ b/site/src/content/docs/project/roadmap.mdx
@@ -0,0 +1,66 @@
+---
+title: Roadmap & Releases
+description: Track the release history, unreleased integration scope, and future milestones of notMyShell.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+## Tracking
+
+| Milestone | Status |
+|---|---|
+| **Current Stable Release** | [v0.17.0 — Context Engine, Themes & Discovery](https://github.com/raiseCatError/notMyShell/releases/tag/v0.17.0) |
+| **macOS Distribution** | Homebrew: `brew install raiseCatError/tap/nmsh` |
+| **Active Integration Candidate** | [v0.18.0 (PR #345)](https://github.com/raiseCatError/notMyShell/pull/345) on `release/v0.18.0` |
+| **Development Branch** | `dev` |
+
+GitHub issues define actionable remaining work. Closed issues represent completed work, not a promise that future refinements are finished.
+
+---
+
+## Implemented, Unreleased — v0.18.0
+
+
+
+The upcoming v0.18.0 release unites the Context Engine platform, managed agents, and workspace tools into a cohesive integration candidate (PR #345 on `release/v0.18.0`).
+
+### Context Engine Platform & Module Ecosystem (#305)
+- **Capability Scheduling**: Demand-driven capability scheduler featuring concurrency caps, timeouts, backoff, and cancellation.
+- **First-Party Pack Catalog**: All 7 bundled declarative packs (`nmsh.project`, `nmsh.environment`, `nmsh.infrastructure`, `nmsh.cloud`, `nmsh.system`, `nmsh.vcs`, `nmsh.agents`) shipping under `nmsh.context-pack/v1`.
+- **Pack Lifecycle CLI**: `nmsh packs` subcommands (`list`, `inspect`, `install`, `remove`, `enable`, `disable`) with sha256 verification and automatic module discovery in `/prompt`.
+- **Coding Assistant Context**: Claude Code session telemetry via its official status line (`nmsh agent-status`), showing model, token usage, cost, and rate-limit countdowns without terminal scraping.
+- **Surface Routing**: Status Strip 2.0 routing, `/modules` management, and Context Rail fitting.
+
+### Managed Agents & Workspaces (#329, #342, #343, #344, #346)
+- **Worktree Manager (`/worktrees`)**: Interactive git worktree planning, branch switching, and safe removal safeguards.
+- **GitHub Workspaces (`/github`, `/prs`, `/issues`)**: Read-only repository telemetry over the local `gh` CLI.
+- **Managed Agent Workspaces (`/claude`, `/ai`)**: Full-height terminal workspace management for coding assistant sessions.
+- **Menu System (`/mods`)**: Native menu navigation with accessible styling for non-color terminals.
+
+### Semantic Terminal & Theme Bridge (#304)
+- **Terminal Title Ownership**: Clean window and tab title ownership via OSC 0/2 escapes; restores the host's prior title upon exit.
+- **Theme Bridge**: Truthful delta status and verified 16/8-color terminal correctness.
+- **Transcript Integrity**: Output boundary repairs after terminal clears and Fish editor keystroke protection.
+
+---
+
+## Recently Released — v0.17.0
+
+Released stable version. Includes:
+- **Theme Studio (`/theme`)**: Built-in, Imported, and Custom themes with live previews.
+- **Theme Bridge (`/theme-bridge`)**: Synchronize NMSh themes to `fzf`, `bat`, `tmux`, `less`, `vim`, `neovim`, and `helix`.
+- **Context Engine Foundation**: Typed fact metadata, trust levels, and the Context Rail.
+- **Curated Tools Browser (`/tools`)**: Detects tools and configures shell frameworks safely.
+- **Keep Awake (`/zoomies`, `/caffeinate`, `/awake`)**: OS-level sleep inhibition with configurable timeouts and composer edge presentation.
+
+---
+
+## Future Scope & Backlog
+
+These items are deferred to future milestones and are not part of the v0.18.0 release candidate:
+
+- **Remote Pack Registry**: Download, package repositories, and signature trust verification.
+- **Executable Extension Tier**: Arbitrary third-party executable extension execution (would require a sandboxing runtime).
+- **Additional Shell Backends**: Nushell and PowerShell implementations for the ShellAdapter.
+- **Lone Scrollback Clears**: Refining the handling of standalone `ESC[3J` escapes post-v0.18.
+- **Hosted SSH Demos**: Hosted demonstration environments (post-1.0).
diff --git a/site/src/content/docs/reference/commands.mdx b/site/src/content/docs/reference/commands.mdx
new file mode 100644
index 00000000..2949a88a
--- /dev/null
+++ b/site/src/content/docs/reference/commands.mdx
@@ -0,0 +1,128 @@
+---
+title: Commands & Flags
+description: Complete reference for NMSh CLI arguments, maintenance subcommands, and slash-commands.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+notMyShell maintains a clean boundary between its own control plane and your shell's namespace. The `nmsh` executable is used to launch the frontend, reattach daemon sessions, and run maintenance commands outside of an interactive terminal session. Inside an active session, **slash commands** (`/`) control the frontend.
+
+## CLI Flags & Arguments
+
+When launching `nmsh` from your terminal:
+
+| Invocation | Action |
+|---|---|
+| `nmsh` | Default launch. Attaches to an available detached session, or opens the interactive Startup Picker if multiple detached sessions exist. If none exist, launches a new session. |
+| `nmsh --new` | Start a fresh session, bypassing the Startup Picker and ignoring detached sessions. |
+| `nmsh --sessions` | List all live daemon sessions with their state (`attached` vs `detached`), session ID, and duration. |
+| `nmsh --attach ` | Explicitly attach to a specific live session ID. Fails with an exit code if the session is already attached elsewhere. |
+| `nmsh --presets` | List configured startup presets, their working directory, and startup commands. |
+| `nmsh --preset ` | Launch a new session initialized with the specified session preset. |
+| `nmsh --version` | Print NMSh build identity, version, commit, and platform architecture. |
+
+> **Recursive Protection**: Launching `nmsh` from within an already NMSh-managed shell is rejected (`NESTED_NMSH_MESSAGE`). NMSh refuses to nest frontend instances.
+
+---
+
+## Maintenance Subcommands
+
+These CLI subcommands run non-interactively or in maintenance mode, and can be safely executed from outside or inside an NMSh session:
+
+### `nmsh config` — Configuration Management
+- `nmsh config path`: Prints the absolute path to `config.json`.
+- `nmsh config categories`: Lists all 18 portable settings categories (`prompt`, `theme`, `themeBridge`, `chroma`, `chrome`, etc.).
+- `nmsh config export [--categories a,b] [--output FILE [--force]]`: Exports settings to JSON (stdout by default). Never exports sensitive paths, credentials, history, or transcripts.
+- `nmsh config import FILE [--categories a,b] [--yes]`: Validates and previews changes, showing an interactive diff before prompting to apply.
+
+### `nmsh doctor` — Environment Health Check
+Prints a short, pasteable diagnostic report for issue reports and troubleshooting. Contains no secrets, command history, or environment dumps:
+- Reports NMSh version and installation provenance (e.g. Homebrew tap vs npm global).
+- Node version, OS platform, architecture, and kernel support tier.
+- Terminal host identification and detected VT capabilities.
+- Active providers for prompt, suggestions, history, navigation, and pickers.
+- Default shell backend executable path, configuration path, and daemon runtime directory.
+
+### `nmsh uninstall` — Clean Removal
+```bash
+nmsh uninstall [--dry-run] [--delete-data] [--yes]
+```
+- Removes the `nmsh` launcher links created during installation after displaying an interactive preview.
+- Settings, transcripts, and telemetry are preserved unless `--delete-data` is specified.
+- **Shell configuration files (`~/.zshrc`, `~/.bashrc`, `~/.config/fish/config.fish`) are never modified.**
+
+### `nmsh packs` — Context Engine Packs
+- `nmsh packs` or `nmsh packs list`: List all bundled and installed declarative Context Packs.
+- `nmsh packs inspect FILE`: Validate a pack manifest and display what capabilities and files it reads.
+- `nmsh packs install FILE [--sha256 HEX] [--replace] [--yes]`: Installs a pack into `context-packs/`. Modules start hidden until toggled in `/prompt`.
+- `nmsh packs remove ID [--yes]`: Removes an installed pack and cleans up its module configuration entries.
+- `nmsh packs enable ID` / `disable ID`: Toggles an installed pack on or off.
+
+### `nmsh agent-status` — Coding Assistant Integration
+- `nmsh agent-status`: Shows whether Claude Code is configured to report to NMSh, along with the most recent status report.
+- `nmsh agent-status setup [--yes]`: Shows the exact setting modification before configuring NMSh as Claude Code's status line.
+- `nmsh agent-status remove [--yes]`: Cleanly removes the status line NMSh added.
+- `nmsh agent-status claude`: The bridge handler invoked by Claude Code with JSON on stdin.
+
+---
+
+## Slash Commands (Internal Frontend UI)
+
+Type `/` in the composer to open the Command Palette, or use `Ctrl+Shift+P` / `F1`.
+
+### Appearance & Themes
+| Command | Description |
+|---|---|
+| `/theme` | Open Theme Studio: choose, edit, import, or export themes. |
+| `/theme-bridge` | Open Theme Bridge: synchronize NMSh themes to `fzf`, `bat`, `tmux`, `less`, `vim`, `neovim`, and `helix`. |
+| `/appearance` | Configure terminal appearance, theme family, and colors. |
+| `/chroma` | Open Chroma: configure prompt palettes, motion, and custom gradients. |
+| `/chrome` | Configure UI Chrome: rules, frames, tabs, and accents. |
+| `/cursor` | Configure text caret shape, blink, and effects. |
+| `/motion` | Configure UI motion: context transitions, command launch, and completion effects. |
+| `/glyphs` | Configure glyph styles: switch between Nerd Font icons and Safe Unicode symbols. |
+| `/strip` (or `/status-strip`) | Status Strip Studio: configure bottom/top bar groups, telemetry, and live preview. |
+| `/screensaver` | Idle visuals: configure screensavers, timeouts, and colors (`/screensaver start` launches immediately). |
+| `/activity` | Live command activity indicators and colors. |
+
+### Composer, Prompt & Transcript
+| Command | Description |
+|---|---|
+| `/prompt` | Configure prompt styles, powerline connectors, and layout. |
+| `/modules` | Configure and route Context Engine modules to surfaces. |
+| `/layout` (or `/composer`) | Select composer docking (`bottom`, `top`, `flow`) and transcript format (`normal`, `chat`). |
+| `/syntax` | Configure syntax highlighting colors and token presentation. |
+| `/transcript` | Configure transcript formatting, dividers, and output folding. |
+| `/keyboard` | Configure keyboard protocol and shortcut handling. |
+| `/copy [N]` | Copy the latest output without ANSI escapes (`/copy N` copies Nth previous output). |
+| `/find [term]` | In-transcript search (`Ctrl+F`). Supports regex (`-r`), case-matching (`-c`), and term removal. |
+| `/filter [term]`| Filter transcript rows for focused output. Supports invert (`-v`) and context rows (`-C N`). |
+| `/clear` | Archive the current viewport and start a clean transcript buffer (history is preserved). |
+
+### Tools & Integrations
+| Command | Description |
+|---|---|
+| `/tools` | Browse curated shell tools, installation previews, and configuration. |
+| `/caffeinate` (or `/awake`, `/zoomies`) | Keep Awake: prevent computer or display from sleeping (`idle`, `display`, `system`, `all`; optional duration like `30m`). |
+| `/tmux` | tmux Config Studio: configure settings, status line, and pane integration. |
+| `/integrations` | Inspect health of managed integrations. |
+| `/dotfiles ` | Import settings from a dotfiles directory or Git repo (reviewed, never executed). |
+| `/configure `| Configure supported third-party tools. |
+
+### Shell & Session Control
+| Command | Description |
+|---|---|
+| `/shell [zsh|fish|bash]`| Switch the running session's shell backend in place without restarting NMSh. |
+| `/sessions` | View and manage live sessions; switch between detached sessions or kill a session. |
+| `/resume` | Browse and view archived session transcripts. |
+| `/presets` | Create, inspect, and launch named session presets. |
+| `/zsh`, `/fish`, `/bash` | Escape NMSh and hand off the terminal to an ordinary interactive shell. Running `nmsh` there returns back to this session. |
+| `/exit` | Exit NMSh and hand off to your configured default shell. |
+| `/rename ` | Rename the active live session for display identification. |
+| `/watch ` | Run a command repeatedly and highlight changes (`/watch git status --every 10s`). |
+| `/btw [question]` (or `/ask`) | Query local intelligence for command assistance. |
+| `/ai` | View or launch coding agent harnesses (`/ai claude`). |
+| `/doctor` | Run an in-session health check. |
+| `/update` | Check for updates (`/update apply` installs available releases). |
diff --git a/site/src/content/docs/reference/configuration.mdx b/site/src/content/docs/reference/configuration.mdx
new file mode 100644
index 00000000..86c1deba
--- /dev/null
+++ b/site/src/content/docs/reference/configuration.mdx
@@ -0,0 +1,126 @@
+---
+title: Configuration
+description: Complete reference for NMSh configuration paths, settings schema, and portable transfer format.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh avoids merging shell dotfiles, creating wrapper scripts, or silently modifying your environment. Everything about the frontend is configured through its internal UI, which serializes safely to a well-known JSON file.
+
+## Configuration File Locations
+
+Configuration paths adhere to platform standards via `src/configuration/paths.ts`:
+
+- **macOS (`darwin`)**:
+ ```text
+ ~/Library/Application Support/notMyShell/config.json
+ ```
+- **Linux & other platforms**:
+ ```text
+ ~/.config/nmsh/config.json
+ ```
+ *(If `$XDG_CONFIG_HOME` is set, `$XDG_CONFIG_HOME/nmsh/config.json` is used instead).*
+
+Run the following command at any time to print the exact path on your active system:
+```bash
+nmsh config path
+```
+
+> **Important**: Do not edit `config.json` while NMSh is running. Settings are managed through `/settings`, the Command Palette, and dedicated configuration studios (Theme Studio, tmux Config Studio).
+
+## Exporting & Importing
+
+Configuration is strictly typed, versioned (`nmsh-settings` format), and exportable via `nmsh config`.
+
+An export never contains machine-specific paths, credentials, shell history, transcripts, onboarding status, or third-party config paths (`starship`, `powerlevel10k`, `ohMyPosh`).
+
+### Exporting Settings
+
+Export all portable settings:
+```bash
+nmsh config export --output my-nmsh-settings.json
+```
+
+Export specific categories:
+```bash
+nmsh config export --categories prompt,theme,themeBridge --output theme-bundle.json
+```
+
+### Importing Settings
+
+Importing always inspects the file, validates every value, and presents an interactive diff preview showing exact before-and-after values before modifying disk:
+```bash
+nmsh config import my-nmsh-settings.json
+```
+
+Use `--yes` to accept the preview non-interactively:
+```bash
+nmsh config import my-nmsh-settings.json --yes
+```
+
+### Real Portable Category IDs
+
+NMSh defines 18 exact category IDs in `src/configuration/portability.ts`. You can list them anytime using `nmsh config categories`:
+
+| Category ID | Managed Configuration Properties |
+|---|---|
+| `prompt` | Prompt provider, symbol, powerline geometry, connectors, Rich Git colors/geometry, style profiles, and module placements. |
+| `theme` | Native palette (`lavender`, `brand`, etc.), Catppuccin accent, vibrance, active theme ID, custom theme, and imported themes. |
+| `themeBridge` | Theme Bridge integrations (`fzf`, `bat`, `tmux`, `less`, `ls`, `vim`, `neovim`, `helix`). |
+| `chroma` | Semantic color treatments and presentation settings. |
+| `chrome` | UI Chrome, glyph style (`nerd` vs `safe`), and cursor appearance. |
+| `syntax` | Semantic syntax highlighting toggle, color mode, and theme. |
+| `transcript` | Transcript block styling and output folding mode (`smart`). |
+| `layout` | Composer layout (`oneLine`, `twoLine`), position (`bottom`, `top`, `flow`), and transcript presentation (`normal`, `chat`). |
+| `suggestions` | Suggestion provider and empty-buffer suggestion toggle. |
+| `providers` | Backend providers for history, pickers, directory navigation, and welcome screen. |
+| `statusStrip` | Status Strip modules, groups, and presentation. |
+| `idle` | Idle scene visuals, screensavers, and live command activity indicators. |
+| `notifications` | Command completion notifications, threshold seconds, and session notices. |
+| `tools` | Tool update checks, install suggestions, ignored tools, and update check frequency. |
+| `sessions` | Live session startup policy (`ask`, `always`, `never`), multiple session policy, session retention count, and terminal title modes. |
+| `agents` | Agent activity tracking toggle. |
+| `shell` | Default shell backend (`zsh`, `bash`, `fish`). |
+| `editor` | File/URL launcher integration (`openWith`: `auto`, `open`, `xdg-open`, or host-specific). |
+
+## Core Settings & Defaults
+
+Default values are established in `src/prompt/configuration.ts`:
+
+- **Shell Backend (`shellBackend`)**: `zsh` (Bash 4.4+ and Fish 3.1+ supported).
+- **Prompt Provider (`provider`)**: `nmsh` (Native powerline prompt with Rich Git).
+- **Composer Position (`composerPosition`)**: `bottom` (Options: `bottom`, `top`, `flow`).
+- **Composer Layout (`composerLayout`)**: `twoLine` (Options: `oneLine`, `twoLine`).
+- **Transcript Presentation (`transcriptPresentation`)**: `normal` (Options: `normal`, `chat`).
+- **Output Folding (`outputFolding`)**: `smart` (Long outputs fold into expandable blocks).
+- **Suggestions Provider (`suggestions`)**: `nmsh` (Native shell-evaluated autocompletion).
+- **History Provider (`history`)**: `native` (Structured SQLite history).
+- **Picker Provider (`picker`)**: `native` (Terminal-native interactive picker).
+- **Navigation Provider (`navigation`)**: `native` (Directory stack tracking).
+- **Welcome Screen (`welcome`)**: `vespyr` (Options: `vespyr`, `fastfetch`, `neofetch`, `macchina`, `zigfetch`, `none`).
+- **Live Session Startup (`liveSessionStartup`)**: `ask` (Prompts to reattach detached sessions).
+- **Session Retention (`sessionRetention`)**: `1000` archived transcripts.
+- **Update Checks (`updateMode`, `updateFrequency`)**: `automatic`, `daily`.
+- **Paste Preview (`pastePreview`)**: `smart` (Multiline paste confirmation review).
+- **Glyph Style (`glyphStyle`)**: `nerd` (Fallback: `safe` Unicode glyphs).
+- **Terminal Title (`terminalTitle`)**: `off` (Options: `off`, `minimal`, `verbose` via OSC 0/2 escapes).
+- **Cursor Appearance (`cursor`)**: Shape: `host`, Blink: `host`, Motion: `off`, Effect: `none`.
+
+## Context Packs Storage
+
+Installed declarative Context Packs for the Context Engine are stored in the `context-packs/` directory under NMSh's configuration directory:
+
+- **macOS**: `~/Library/Application Support/notMyShell/context-packs/`
+- **Linux**: `~/.config/nmsh/context-packs/` (or `$XDG_CONFIG_HOME/nmsh/context-packs/`)
+
+Packs can be inspected, installed, enabled, disabled, and removed via the `nmsh packs` CLI.
+
+## Runtime Directory & Sockets
+
+NMSh runs a background session service daemon. Ephemeral session sockets and stream journals are stored in a private per-user runtime directory verified at launch:
+
+- **Linux**: `$XDG_RUNTIME_DIR/nmsh/` (or `/tmp/nmsh-/` if unset)
+- **macOS**: `$TMPDIR/nmsh-/`
+- Override with the `NMSH_RUNTIME_DIR` environment variable.
diff --git a/site/src/content/docs/reference/keyboard-shortcuts.mdx b/site/src/content/docs/reference/keyboard-shortcuts.mdx
new file mode 100644
index 00000000..c7ec947c
--- /dev/null
+++ b/site/src/content/docs/reference/keyboard-shortcuts.mdx
@@ -0,0 +1,79 @@
+---
+title: Keyboard Shortcuts
+description: Comprehensive keyboard shortcuts reference for NMSh editing, navigation, and panel control.
+---
+
+import Availability from '../../../components/Availability.astro';
+
+
+
+NMSh provides rich, native editor keybindings across macOS, Linux, and Windows terminal hosts. It natively supports the **Kitty keyboard protocol** (utilized by modern emulators like Ghostty and Kitty) for unambiguous modifier detection, while preserving traditional terminal escape sequences.
+
+## Input & Multiline Editing
+
+| Shortcut | Action | Notes |
+|---|---|---|
+| `Enter` | Submit command | Executes current buffer in the live shell. |
+| `Shift + Enter` | Insert newline | True multiline input support. |
+| `Ctrl + J` | Fallback newline | Alternate newline trigger for standard terminal configurations. |
+| `Backspace` | Delete character before caret | Standard backspace. |
+| `Option + Backspace` / `Alt + Backspace` | Delete word before caret | Deletes previous token/word. |
+| `Ctrl + U` | Delete line before caret | Clears from cursor back to the start of the current line. |
+| `Ctrl + K` | Delete line after caret | Clears from cursor forward to the end of the line. |
+| `Delete` | Delete character after caret | Forward deletion. |
+
+## Caret Movement & Text Navigation
+
+| Shortcut | Action | Notes |
+|---|---|---|
+| `Left` / `Right` Arrow | Move caret left / right | Single grapheme movement. |
+| `Alt + Left` / `Option + Left` / `Ctrl + Left` | Move word left | Word boundary navigation. |
+| `Alt + Right` / `Option + Right` / `Ctrl + Right` | Move word right | Word boundary navigation. |
+| `Home` / `Cmd + Left` | Move to start of line | Goes to first character on current row. |
+| `End` / `Cmd + Right` | Move to end of line | Goes to last character on current row. |
+| `Cmd + Up` | Move to buffer start | Jumps to beginning of entire multiline input. |
+| `Cmd + Down` | Move to buffer end | Jumps to end of entire multiline input. |
+
+## Text Selection
+
+NMSh supports terminal-native cursor-driven selection inside the composer:
+
+| Shortcut | Action | Notes |
+|---|---|---|
+| `Shift + Left` / `Shift + Right` | Select character left / right | Expands/contracts selection. |
+| `Shift + Up` / `Shift + Down` | Select row up / down | Multiline vertical selection. |
+| `Alt + Shift + Left` / `Option + Shift + Left` | Select word left | Selects whole word token to the left. |
+| `Alt + Shift + Right` / `Option + Shift + Right` | Select word right | Selects whole word token to the right. |
+| `Cmd + Shift + Left` | Select to line start | Selects everything to beginning of row. |
+| `Cmd + Shift + Right` | Select to line end | Selects everything to end of row. |
+| `Alt + A` / `Cmd + A` | Select entire buffer | Highlights all text in the composer. |
+
+## Autocomplete & Suggestions
+
+| Shortcut | Action | Notes |
+|---|---|---|
+| `Tab` | Accept top suggestion / cycle | Invokes shell tab-completion or accepts top ghost suggestion. |
+| `Right Arrow` / `End` | Accept ghost text | Fills in the suggested completion if caret is at end of input. |
+| `Alt + Right` / `Option + Right` | Accept next word of suggestion | Accepts a single token from ghost text. |
+| `Ctrl + N` | Next suggestion | Cycles downward through completion menu choices. |
+| `Ctrl + P` | Previous suggestion | Cycles upward through completion menu choices. |
+| `Escape` | Dismiss suggestion popup | Closes suggestion overlay without altering input text. |
+
+## Transcript & Viewport Control
+
+| Shortcut | Action | Notes |
+|---|---|---|
+| `PageUp` / `PageDown` | Scroll viewport | Detaches viewport from the bottom to inspect history. |
+| `Ctrl + O` | Toggle output folding | Expands or collapses long command output blocks. |
+| `Ctrl + R` | Interactive history search | Opens history picker with fuzzy filtering. |
+| `Ctrl + F` | Transcript search (`/find`) | Launches in-transcript search bar. |
+| `Ctrl + Shift + P` / `F1` | Command Palette | Launches the slash-command selector. |
+| `Shift + Tab` | Focus previous control | Cycles focus between composer, status bar, and active accessories. |
+
+## Terminal Host Integration Details
+
+### Ghostty & Kitty
+When running in Ghostty or Kitty, NMSh negotiates Kitty keyboard protocol flags (`CSI > 1 u`). This eliminates ambiguous escape sequences (such as distinguishing `Escape` from Alt-prefixed characters) and enables key combinations like `Cmd+Arrow` and `Shift+Enter` out of the box.
+
+### macOS Terminal.app & iTerm2
+In Terminal.app and iTerm2, ensure **"Use Option as Meta key"** or "Esc+" is enabled in your profile settings to allow `Option+Backspace` and word navigation keys to function properly.
diff --git a/site/src/custom.css b/site/src/custom.css
new file mode 100644
index 00000000..663ecc08
--- /dev/null
+++ b/site/src/custom.css
@@ -0,0 +1,28 @@
+:root {
+ /* NMSh Lavender: #A67CF3 */
+ --sl-color-accent-low: #28164b;
+ --sl-color-accent: #a67cf3;
+ --sl-color-accent-high: #dfccfe;
+
+ /* Text adjustments for better contrast with the accent */
+ --sl-color-white: #ffffff;
+ --sl-color-black: #000000;
+
+ /* Dark mode specific tweaks if needed */
+}
+
+/* Light mode overrides */
+:root[data-theme='light'] {
+ --sl-color-accent-low: #f3ecff;
+ --sl-color-accent: #8b55e8;
+ --sl-color-accent-high: #5821b0;
+}
+
+/* Custom font styles (optional, can be expanded later) */
+body {
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+}
+
+code {
+ font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
diff --git a/site/src/styles/global.css b/site/src/styles/global.css
new file mode 100644
index 00000000..a461c505
--- /dev/null
+++ b/site/src/styles/global.css
@@ -0,0 +1 @@
+@import "tailwindcss";
\ No newline at end of file
diff --git a/site/tsconfig.json b/site/tsconfig.json
new file mode 100644
index 00000000..8bf91d3b
--- /dev/null
+++ b/site/tsconfig.json
@@ -0,0 +1,5 @@
+{
+ "extends": "astro/tsconfigs/strict",
+ "include": [".astro/types.d.ts", "**/*"],
+ "exclude": ["dist"]
+}