docs(moosestack): migrate reference suite and nav

.github/workflows/test-framework-cli.yaml

@@ -43,8 +43,8 @@ jobs:
             "^\.github/workflows/test-framework-cli\.yaml"
             "^apps/framework-cli-e2e/"
             "^apps/framework-cli/"
-            "^templates/python/"
-            "^templates/typescript/"
+            "^templates/python"
+            "^templates/typescript"
             "^packages/"
             "Cargo.lock"
             "pnpm-lock.yaml"
@@ -716,6 +716,138 @@ jobs:
         run: |
           cat ~/.moose/*-cli.log
 
+  test-e2e-cluster-typescript:
+    needs:
+      [detect-changes, check, test-cli, test-ts-moose-lib, test-py-moose-lib]
+    if: needs.detect-changes.outputs.should_run == 'true'
+    name: Test E2E Cluster Support - TypeScript (Node 20)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      RUST_BACKTRACE: full
+    steps:
+      - name: Install Protoc (Needed for Temporal)
+        uses: arduino/setup-protoc@v3
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: "23.x"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      # Login to Docker hub to get higher rate limits when moose pulls images
+      - name: Login to Docker Hub
+        uses: ./.github/actions/docker-login
+        with:
+          op-service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Get system info
+        id: system
+        run: |
+          echo "version=$(lsb_release -rs)" >> $GITHUB_OUTPUT
+          echo "distro=$(lsb_release -is)" >> $GITHUB_OUTPUT
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          cache: true
+          cache-shared-key: ${{ runner.os }}-${{ steps.system.outputs.distro }}-${{ steps.system.outputs.version }}-${{ runner.arch }}-rust
+          cache-on-failure: true
+          cache-all-crates: true
+          cache-workspace-crates: true
+
+      - name: Run TypeScript Cluster E2E Tests
+        run: pnpm install --frozen-lockfile && pnpm --filter=framework-cli-e2e run test -- --grep "TypeScript Cluster Template"
+        env:
+          MOOSE_TELEMETRY_ENABLED: false
+
+      - name: Inspect Logs
+        if: always()
+        run: |
+          cat ~/.moose/*-cli.log
+
+  test-e2e-cluster-python:
+    needs:
+      [detect-changes, check, test-cli, test-ts-moose-lib, test-py-moose-lib]
+    if: needs.detect-changes.outputs.should_run == 'true'
+    name: Test E2E Cluster Support - Python (Python 3.13)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      RUST_BACKTRACE: full
+    steps:
+      - name: Install Protoc (Needed for Temporal)
+        uses: arduino/setup-protoc@v3
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: "23.x"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      # Login to Docker hub to get higher rate limits when moose pulls images
+      - name: Login to Docker Hub
+        uses: ./.github/actions/docker-login
+        with:
+          op-service-account-token: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Get system info
+        id: system
+        run: |
+          echo "version=$(lsb_release -rs)" >> $GITHUB_OUTPUT
+          echo "distro=$(lsb_release -is)" >> $GITHUB_OUTPUT
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          cache: true
+          cache-shared-key: ${{ runner.os }}-${{ steps.system.outputs.distro }}-${{ steps.system.outputs.version }}-${{ runner.arch }}-rust
+          cache-on-failure: true
+          cache-all-crates: true
+          cache-workspace-crates: true
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.13"
+
+      - name: Upgrade Python build tools
+        run: pip install --upgrade pip setuptools wheel
+
+      - name: Run Python Cluster E2E Tests
+        run: pnpm install --frozen-lockfile && pnpm --filter=framework-cli-e2e run test -- --grep "Python Cluster Template"
+        env:
+          MOOSE_TELEMETRY_ENABLED: false
+
+      - name: Inspect Logs
+        if: always()
+        run: |
+          cat ~/.moose/*-cli.log
+
   lints:
     needs: detect-changes
     if: needs.detect-changes.outputs.should_run == 'true'
@@ -776,8 +908,10 @@ jobs:
         test-e2e-typescript-tests,
         test-e2e-python-default,
         test-e2e-python-tests,
-        test-e2e-backward-compatibility-typescript,
+#        test-e2e-backward-compatibility-typescript,
         test-e2e-backward-compatibility-python,
+        test-e2e-cluster-typescript,
+        test-e2e-cluster-python,
         lints,
       ]
     if: always()
@@ -805,8 +939,9 @@ jobs:
              [[ "${{ needs.test-e2e-typescript-tests.result }}" == "failure" ]] || \
              [[ "${{ needs.test-e2e-python-default.result }}" == "failure" ]] || \
              [[ "${{ needs.test-e2e-python-tests.result }}" == "failure" ]] || \
-             [[ "${{ needs.test-e2e-backward-compatibility-typescript.result }}" == "failure" ]] || \
              [[ "${{ needs.test-e2e-backward-compatibility-python.result }}" == "failure" ]] || \
+             [[ "${{ needs.test-e2e-cluster-typescript.result }}" == "failure" ]] || \
+             [[ "${{ needs.test-e2e-cluster-python.result }}" == "failure" ]] || \
              [[ "${{ needs.lints.result }}" == "failure" ]]; then
             echo "One or more required jobs failed"
             exit 1
@@ -820,8 +955,9 @@ jobs:
              [[ "${{ needs.test-e2e-typescript-tests.result }}" == "success" ]] && \
              [[ "${{ needs.test-e2e-python-default.result }}" == "success" ]] && \
              [[ "${{ needs.test-e2e-python-tests.result }}" == "success" ]] && \
-             [[ "${{ needs.test-e2e-backward-compatibility-typescript.result }}" == "success" ]] && \
              [[ "${{ needs.test-e2e-backward-compatibility-python.result }}" == "success" ]] && \
+             [[ "${{ needs.test-e2e-cluster-typescript.result }}" == "success" ]] && \
+             [[ "${{ needs.test-e2e-cluster-python.result }}" == "success" ]] && \
              [[ "${{ needs.lints.result }}" == "success" ]]; then
             echo "All required jobs succeeded"
             exit 0

AGENTS.md

@@ -1,117 +1,78 @@
 # AGENTS.md
 
-When you are changing MooseStack functionality (either in the language specific libraries or in the Rust core) ALWAYS run the
-end-to-end tests to make sure you did not break anything.
-
-When you change user facing functionality for moose, always add end-to-end tests for the `python-tests` and `typescript-tests`
-templates and ALWAYS audit for the documentation for update needs. Those projects are Moose project that should be using Moose code.
-The checks if the moose code works as expected should be inside `apps/framework-cli-e2e`. 
-
-You can find the logs for moose if you need to troublehoot into `~/.moose/*-cli.log`
-
-## Commands
-
-### Build and Development
-- **Build all packages**: `pnpm build` (uses Turbo Repo)
-- **Development mode**: `pnpm dev` (starts development servers)
-- **Linting**: `pnpm lint`
-- **Formatting**: `pnpm format` (Prettier on TypeScript/JavaScript files)
-- **Clean build artifacts**: `pnpm clean`
-
-### Rust Components
-- **Build Rust**: `cargo build`
-- **Run Rust tests**: `cargo test`
-- **Lint Rust code**: `cargo clippy --all-targets -- -D warnings` (no warnings allowed)
-- **Format Rust code**: `rustfmt --edition 2021 <file.rs>`
-
-### Testing
-
-#### Unit Tests (Library Testing)
-- **Rust tests**: `cargo test`
-- **TypeScript library tests**: Navigate to `./packages/ts-moose-lib` and run `pnpm test`
-- **Python library tests**: Navigate to `./packages/py-moose-lib` and run `pytest`
-
-Unit tests should be colocated with the library code they test:
-- TypeScript library tests: `packages/ts-moose-lib/tests/`
-- Python library tests: `packages/py-moose-lib/tests/`
-- Rust tests: Inline with code using `#[cfg(test)]` modules
-
-#### End-to-End Tests (Template Integration Testing)
-- **End-to-end tests**: Navigate to `./apps/framework-cli-e2e` and run `pnpm test`
-
-End-to-end tests verify that complete MooseStack applications work correctly:
-- Tests use the templates in `templates/` as working Moose applications
-- Templates like `python-tests` and `typescript-tests` are complete MooseStack projects
-- E2E tests verify infrastructure creation, data ingestion, API responses, etc.
-
-#### Testing Distinction: Templates vs Libraries
-**IMPORTANT**: Templates are NOT for library unit tests. They are working MooseStack applications.
-
-- **Templates** (`templates/python-tests`, `templates/typescript-tests`): 
-  - Complete, runnable Moose applications
-  - Used by E2E tests to verify end-to-end functionality
-  - Should demonstrate features and serve as examples
-  - Tested by `apps/framework-cli-e2e`
-
-- **Library Tests** (`packages/*/tests/`):
-  - Unit tests for library functionality
-  - Test individual functions, classes, and modules
-  - Should be colocated with the library code
-  - Run independently of the CLI or infrastructure
-
-## Repository Architecture
-
-### Monorepo Structure
-This is a multi-language monorepo using:
-- **PNPM workspaces** with **Turbo Repo** for JavaScript/TypeScript packages
-- **Cargo workspace** for Rust components
-- **Cross-language integration** between Rust CLI and TypeScript/Python libraries
-
-### Key Directories
-- `apps/`: End-to-end tests, CLI application, docs, and distribution packages
-  - `framework-cli/`: Main Rust CLI application
-  - `framework-docs/`: Documentation site
-  - `framework-cli-e2e/`: End-to-end test suite
-- `packages/`: Shared libraries and common dependencies
-  - `ts-moose-lib/`: TypeScript library for MooseStack
-  - `py-moose-lib/`: Python library for MooseStack
-  - `protobuf/`: Protocol buffer definitions
-- `templates/`: Standalone Moose project templates
-
-### Core Technologies
-- **Rust**: CLI application, performance-critical components
-- **TypeScript**: Developer libraries, web interfaces
-- **Python**: Alternative developer library
-- **ClickHouse**: OLAP database
-- **Redpanda/Kafka**: Streaming platform
-- **Temporal**: Workflow orchestration
-- **Redis**: Internal state management
-
-### Architecture Patterns
-- **Code-first infrastructure**: Declare tables, streams, APIs in code
-- **Type-safe development**: Strong typing across TypeScript and Rust
-- **Modular design**: Independent modules (OLAP, Streaming, Workflows, APIs)
-- **Local-first development**: Full production mirror via `moose dev`
-
-## Development Guidelines
-
-### Pre-commit Requirements
-- **TypeScript/JavaScript**: Must pass linting and code formating checks (`npx lint-staged`)
-- **Rust**: Must pass `cargo clippy --all-targets -- -D warnings` (no warnings permitted)
-- **All components**: Tests must pass before PR submission
-
-### Error Handling (Rust)
-- Define error types near their unit of fallibility (no global `Error` type)
-- Use `thiserror` for error definitions with `#[derive(thiserror::Error)]`
-- Structure errors in layers with context and specific variants
-- Never use `anyhow::Result` - refactor to use `thiserror`
-
-### Code Standards
-- **Constants**: Use `const` in Rust, place in `constants.rs` at appropriate module level
-- **Newtypes**: Use tuple structs with validation constructors
-- **Documentation**: All public APIs must be documented
-- **Linting**: Always run `cargo clippy --all-targets -- -D warnings` for Rust code
-- Follow existing patterns and conventions in each language
-
-### Templates
-Templates in the `templates/` directory must be able to run in isolation. When modifying templates, verify they can still function as standalone projects.
+Multi-language monorepo (Rust CLI + TypeScript/Python libraries) using PNPM workspaces, Turbo Repo, and Cargo workspace.
+
+**CRITICAL**: When changing MooseStack functionality, ALWAYS run end-to-end tests. When changing user-facing features, add E2E tests to `python-tests`/`typescript-tests` templates AND audit documentation. Logs: `~/.moose/*-cli.log`. Always format the code.
+
+## Build & Development Commands
+
+### All Languages
+- **Build all**: `pnpm build` (Turbo orchestrates builds)
+- **Dev mode**: `pnpm dev` (starts dev servers)
+- **Clean**: `pnpm clean`
+- **Lint all**: `pnpm lint`
+- **Format**: `pnpm format` (Prettier for TS/JS)
+
+### Rust
+- **Build**: `cargo build`
+- **Debug CLI**: Use debug build with verbose logging for ALL moose CLI commands:
+  ```bash
+  RUST_LOG=debug RUST_BACKTRACE=1 MOOSE_LOGGER__LEVEL=Debug ~/repos/moosestack/target/debug/moose-cli <command>
+  ```
+  Example: `RUST_LOG=debug RUST_BACKTRACE=1 MOOSE_LOGGER__LEVEL=Debug ~/repos/moosestack/target/debug/moose-cli init my-app typescript`
+- **Test all**: `cargo test`
+- **Test single**: `cargo test <test_name>` or `cargo test --package <package_name> --test <test_file>`
+- **Lint**: `cargo clippy --all-targets -- -D warnings` (REQUIRED pre-commit, no warnings allowed)
+- **Format**: `cargo fmt`
+
+### TypeScript
+- **Test lib**: `cd packages/ts-moose-lib && pnpm test` (runs mocha tests)
+- **Test single**: `cd packages/ts-moose-lib && pnpm test --grep "test name pattern"`
+- **Typecheck**: `cd packages/ts-moose-lib && pnpm typecheck`
+
+### Python
+- **Test lib**: `cd packages/py-moose-lib && pytest`
+- **Test single**: `cd packages/py-moose-lib && pytest tests/test_file.py::test_function_name`
+- **Test pattern**: `cd packages/py-moose-lib && pytest -k "test_pattern"`
+
+### End-to-End Tests
+- **Run E2E**: `cd apps/framework-cli-e2e && pnpm test` (includes pretest: cargo build, pnpm build, package templates)
+- **Single E2E test**: `cd apps/framework-cli-e2e && pnpm test --grep "test name"`
+
+## Code Style Guidelines
+
+### TypeScript/JavaScript
+- **Imports**: Group by external deps, internal modules, types; use named exports from barrel files (`index.ts`)
+- **Naming**: camelCase for vars/functions, PascalCase for types/classes/components, UPPER_SNAKE_CASE for constants
+- **Types**: Prefer interfaces for objects, types for unions/intersections; explicit return types on public APIs
+- **Unused vars**: Prefix with `_` (e.g., `_unusedParam`) to bypass linting errors
+- **Formatting**: Prettier with `experimentalTernaries: true`; auto-formats on commit (Husky + lint-staged)
+- **ESLint**: Extends Next.js, Turbo, TypeScript recommended; `@typescript-eslint/no-explicit-any` disabled
+
+### Rust
+- **Error handling**: Use `thiserror` with `#[derive(thiserror::Error)]`; define errors near fallibility unit (NO global `Error` type); NEVER use `anyhow::Result`
+- **Naming**: snake_case for functions/vars, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants
+- **Constants**: Place in `constants.rs` at appropriate module level
+- **Newtypes**: Use tuple structs with validation constructors (e.g., `struct UserId(String)`)
+- **Tests**: Inline with `#[cfg(test)]` modules
+- **Documentation**: Required for all public APIs
+
+### Python
+- **Style**: Follow PEP 8; snake_case for functions/vars, PascalCase for classes, UPPER_SNAKE_CASE for constants
+- **Types**: Use type hints for function signatures and public APIs
+- **Tests**: Use pytest with fixtures and parametrize decorators
+
+## Repository Structure
+
+- **`apps/`**: CLI (`framework-cli/`), docs (`framework-docs/`), E2E tests (`framework-cli-e2e/`)
+- **`packages/`**: Libraries (`ts-moose-lib/`, `py-moose-lib/`), shared deps, protobuf definitions
+- **`templates/`**: Standalone Moose apps used by E2E tests (NOT for unit tests)
+
+## Testing Philosophy
+
+- **Library tests** (`packages/*/tests/`): Unit tests colocated with library code
+- **Templates** (`templates/python-tests`, `templates/typescript-tests`): Complete Moose apps for E2E testing; must run in isolation
+
+## Key Technologies
+
+Rust (CLI), TypeScript (libs/web), Python (lib), ClickHouse (OLAP), Redpanda/Kafka (streaming), Temporal (workflows), Redis (state)