new sample doc site + minor updates

Author: CoderOMaster

vitepress-plugin-moss/README.md

@@ -1,6 +1,6 @@
 # vitepress-plugin-moss
 
-A [VitePress](https://vitepress.dev) plugin that adds [Moss](https://moss.dev) semantic (AI) search to your docs. At build time it reads your Markdown source, chunks it, and uploads it to the Moss cloud. At runtime the search UI downloads the index once and runs all queries locally in the browser — no round-trips on every keystroke.
+A [VitePress](https://vitepress.dev) plugin that adds [Moss](https://moss.dev) semantic (AI) search to your docs. At build time it reads your Markdown source, chunks it, and uploads it to the Moss cloud. At runtime the search UI uses a **hot-path**: it queries the cloud immediately so search works from the very first keystroke, while the local model and index download in the background. Once ready, all queries automatically switch to sub-10 ms on-device search — no user action needed.
 
 ---
 
@@ -11,16 +11,16 @@ Build time                                      Runtime (browser)
 ────────────────────────────────────────────    ──────────────────────────────────────
 VitePress calls buildEnd hook                   User presses Ctrl/⌘+K or /
     ↓                                               ↓
-mossIndexerPlugin reads siteConfig              @inferedge/moss downloads the index
+mossIndexerPlugin reads siteConfig              Phase 1 — SDK imported, client created
+    ↓                                           Queries routed to Moss cloud  ← hot-path
+@moss-tools/md-indexer reads source .md             (instant results from first keystroke)
+using VitePress's own markdown renderer             ↓  (parallel)
+(understands includes, extensions, etc.)        Phase 2 — model + index download (background)
     ↓                                               ↓
-@moss-tools/md-indexer reads source .md         Queries run locally < 10 ms
-using VitePress's own markdown renderer             ↓
-(understands includes, extensions, etc.)        Results navigate via metadata.navigation
-    ↓                                           (pre-computed URL + anchor per chunk)
-Uploads via @inferedge-rest/moss REST client
-(deletes old index, then re-uploads chunks)
-    ↓
-Index is live on Moss cloud
+Uploads via @inferedge-rest/moss REST client    Index ready → queries switch to local < 10 ms
+(deletes old index, then re-uploads chunks)         ↓
+    ↓                                           Active query re-run with local index
+Index is live on Moss cloud                     (seamless handoff, no user action needed)
 ```
 
 Two separate npm packages are involved:
@@ -163,46 +163,90 @@ If indexing fails (network error, bad credentials, etc.) the build **does not fa
 
 ---
 
+## Creating and Loading Indexes
+
+### Automatic indexing on build
+
+When you run `vitepress build`, the `mossIndexerPlugin` automatically builds and uploads the index to Moss at the end of the build. No extra step is needed — just make sure your credentials are set in environment variables.
+
+### Manual indexing with `index:docs`
+
+The demo site includes a standalone script for building and uploading the index without running a full VitePress build. This is useful when you update documentation content and want to refresh the index quickly.
+
+```bash
+# From demo-site/
+pnpm index:docs                    # index the documentation/ folder (default)
+pnpm index:docs docs               # index the docs/ folder instead
+pnpm index:docs documentation --inspect   # preview chunks as JSON, no upload
+```
+
+The script:
+
+1. Reads all `.md` files and chunks them using `@moss-tools/md-indexer`
+2. Filters out chunks with 3 or fewer words (lone headings, empty sections, nav-only content)
+3. Uploads the remaining chunks to your Moss index
+
+The `--inspect` flag writes chunks to `.index-preview.json` and exits without uploading — useful for verifying index quality before committing to an upload.
+
+---
+
 ## Testing Locally (Demo Site)
 
-The repository includes a ready-to-use demo site in the `demo-site/` folder. This is the best way to test changes to the plugin.
+The repository includes a demo site in `demo-site/` with two VitePress sites:
+
+- **`documentation/`** — full Moss SDK docs with Moss search enabled (recommended for testing)
+- **`docs/`** — minimal site
 
 ### Step 1 — Build the plugin
 
-First, build the plugin from the root directory to generate the `dist` folder.
+From the repository root:
 
 ```bash
 pnpm install
 pnpm build
 ```
 
-### Step 2 — Set up the Demo Site
-
-Navigate to the demo site directory and install its dependencies.
+### Step 2 — Set up the demo site
 
 ```bash
 cd demo-site
 pnpm install
 ```
 
-### Step 3 — Configure and Build
+Create a `.env` file with your Moss credentials:
+
+```bash
+# demo-site/.env  (never commit this file)
+MOSS_PROJECT_ID=your_project_id
+MOSS_PROJECT_KEY=your_api_key
+MOSS_INDEX_NAME=your_index_name
+```
+
+### Step 3 — Populate the index
 
-The demo site is already configured to use the local plugin. You just need to add your Moss credentials to `demo-site/docs/.vitepress/config.ts` (or use environment variables).
+Before starting the dev server, upload the documentation to your Moss index:
 
 ```bash
-# From inside demo-site/
-npx vitepress build docs
+# From demo-site/
+pnpm index:docs
 ```
 
-### Step 4 — Preview
+You only need to re-run this when you add or change Markdown content.
 
-Start the preview server to test the search modal.
+### Step 4 — Start the dev server
 
 ```bash
-npx vitepress preview docs
+pnpm documentation:dev
 ```
 
-Open [http://localhost:4173](http://localhost:4173) in your browser and verify the search functionality.
+Open [http://localhost:5173](http://localhost:5173) and use `Ctrl/⌘+K` or `/` to test the search modal.
+
+### Production build
+
+```bash
+pnpm docs:build     # builds docs/ site (also runs pnpm build in plugin root first)
+pnpm docs:preview   # preview at http://localhost:4173
+```
 
 ---
 

vitepress-plugin-moss/Search.vue

@@ -5,12 +5,8 @@ import SearchButton from './SearchButton.vue';
 // @ts-ignore — resolved by the virtual module at build time
 import getMossConfig from 'virtual:moss-config';
 
-console.log('[MossSearch] Component loaded');
 const config = getMossConfig();
-console.log('[MossSearch] Config:', config);
 import InferEdgeLogo from './InferEdgeLogo_Dark_Icon.png';
-console.log('[MossSearch] Logo imported:', !!InferEdgeLogo);
-
 
 const isOpen = ref(false);
 const query = ref('');

vitepress-plugin-moss/demo-site/docs/.vitepress/config.ts

@@ -0,0 +1,3 @@
+node_modules/
+cache
+dist

vitepress-plugin-moss/demo-site/docs/guide.md

@@ -0,0 +1,59 @@
+import { defineConfig } from 'vitepress'
+import { mossIndexerPlugin } from 'vitepress-plugin-moss'
+import dotenv from 'dotenv'
+
+dotenv.config({ path: '../.env' })
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  vite: {
+    plugins: [mossIndexerPlugin()]
+  },
+  srcDir: "docs",
+
+  title: "Moss SDK Documentation",
+  description: "Get real-time retrieval inside apps, browsers, and enterprise agents — with centralized management, analytics, and scale built in.",
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }]
+  ],
+  themeConfig: {
+    search: {
+      provider: 'moss' as any,
+      options: {
+        projectId: process.env.MOSS_PROJECT_ID || 'your-project-id',
+        projectKey: process.env.MOSS_PROJECT_KEY || 'your-project-key',
+        indexName: process.env.MOSS_INDEX_NAME || 'moss-sdk-docs',
+      } as any,
+    },
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Moss Portal', link: 'https://usemoss.dev', target: '_blank', rel: 'noopener noreferrer' },
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'JavaScript SDK', link: '/reference/js/README.md' },
+      { text: 'Python SDK', link: '/reference/python/README.md' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Guides',
+        items: [
+          { text: 'Getting Started', link: '/getting-started' }
+        ]
+      },
+      {
+        text: 'SDK References',
+        items: [
+          { text: 'JavaScript SDK Overview', link: '/reference/js/README.md' },
+          { text: 'JavaScript API Reference', link: '/reference/js/globals.md' },
+          { text: 'Python SDK Overview', link: '/reference/python/README.md' },
+          { text: 'Python API Reference', link: '/reference/python/globals.md' },
+          { text: 'Samples', link: 'https://github.com/usemoss/moss-samples' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/usemoss/moss-samples' }
+    ]
+  }
+})

vitepress-plugin-moss/demo-site/docs/index.md

@@ -0,0 +1,61 @@
+# Documentation Maintenance Guide
+
+This guide lives alongside the published site so contributors can regenerate the API reference without exposing internal steps to end users.
+
+## Auto-generated content
+
+The following files are completely generated by tooling and should not be edited manually:
+
+| Path | Source | Command |
+| --- | --- | --- |
+| `docs/reference/js/**/*` | `javascript/user-facing-sdk/typedoc.json` | `npm run docs` (inside `javascript/user-facing-sdk/`) |
+| `docs/reference/python/**/*` | `python/user-facing-sdk/src/inferedge_moss/__init__.pyi` | `python scripts/generate_docs.py` (inside `python/user-facing-sdk/`) |
+
+When these commands run, the contents of those paths are overwritten. Commit the regenerated files after confirming they build.
+
+## Manually maintained content
+
+- `docs/index.md`
+- `docs/getting-started.md`
+- Navigation and sidebar settings in `.vitepress/config.mts`
+
+Update these pages directly to evolve copy, examples, and site structure.
+
+## Regeneration workflow
+
+1. **JavaScript TypeDoc**
+
+   ```bash
+   cd javascript/user-facing-sdk
+   npm install
+   npm run docs
+   ```
+
+   Output lands in `documentation/docs/reference/js/`. (includes `README.md`, `globals.md`, and subfolders)
+
+2. **Python Griffe-based generator**
+
+   ```bash
+   cd python/user-facing-sdk
+   source moss-env/bin/activate  # or your virtualenv
+   pip install -e ".[dev]"  # Ensures griffe is installed
+   python scripts/generate_docs.py
+   ```
+
+   Output lands in `documentation/docs/reference/python/` (includes `globals.md`, `classes/`, `interfaces/`, and `type-aliases/` subdirectories).
+
+3. **Build the site**
+
+   ```bash
+   cd documentation
+   npm install
+   npm run docs:build
+   ```
+
+   Fix any dead-link warnings before committing.
+
+## Tips
+
+- Keep the generated references in sync with SDK releases by running the commands above whenever public APIs change.
+- If the output paths need to change, update the configs listed in the table and reflect the new locations here.
+- To preview changes locally, run `npm run docs:dev` from the `documentation/` folder.