release: browser-extension 1.9.35 — answer engine (fixed build path)

Ships the Hanzo AI answer engine (new-tab landing + address-bar search over the @hanzo/ai search primitive) with the newtab out()-path fix. v1.9.34 was the pre-fix tag; this is the buildable release.
fix(build): newtab.js compiles to the out() root, matching the copy step
2026-07-26 10:35:24 -07:00 · 2026-07-26 10:34:30 -07:00 · 2026-07-26 10:32:50 -07:00 · 2026-07-26 10:32:50 -07:00 · 2026-07-26 01:07:35 -07:00 · 2026-07-25 18:39:56 -07:00
751 changed files with 84463 additions and 5270 deletions
@@ -21,14 +21,17 @@ jobs:
        cache: 'pnpm'
    - run: pnpm install --frozen-lockfile

+    # Build shared workspace libraries first — consumers (slack/teams/…) import
+    # @hanzo/cards via its built dist/, so it must exist before their tests run.
+    - name: Build shared libraries
+      run: pnpm --filter @hanzo/cards build
+
    - name: Test browser extension
      run: pnpm --filter @hanzo/browser-extension test

    - name: Test ACI package
      run: pnpm --filter @hanzo/aci test

-    - name: Test AI package
-      run: pnpm --filter @hanzo/ai test

    - name: Test auth core
      run: pnpm --filter @hanzo/auth test
@@ -36,6 +39,90 @@ jobs:
    - name: Test Office add-in
      run: pnpm --filter @hanzo/office-addin test

+    - name: Test Outlook add-in
+      run: pnpm --filter @hanzo/outlook-addin test
+
+    - name: Test Google Workspace add-on
+      run: pnpm --filter @hanzo/gworkspace-addon test
+
+    - name: Test PDF workspace
+      run: pnpm --filter @hanzo/pdf test
+
+    - name: Test Clio integration
+      run: pnpm --filter @hanzo/clio test
+
+    - name: Test Notion integration
+      run: pnpm --filter @hanzo/notion test
+
+    - name: Test DocuSign integration
+      run: pnpm --filter @hanzo/docusign test
+
+    - name: Test Salesforce (pure helpers)
+      run: pnpm --filter @hanzo/salesforce test
+
+    - name: Test Zendesk app
+      run: pnpm --filter @hanzo/zendesk test
+
+    - name: Test HubSpot app
+      run: pnpm --filter @hanzo/hubspot test
+
+    - name: Test Shopify app
+      run: pnpm --filter @hanzo/shopify test
+
+    - name: Test Figma plugin
+      run: pnpm --filter @hanzo/figma test
+
+    - name: Test Sketch plugin
+      run: pnpm --filter @hanzo/sketch test
+
+    - name: Test Canva app
+      run: pnpm --filter @hanzo/canva test
+
+    - name: Test GitHub App
+      run: pnpm --filter @hanzo/github test
+
+    - name: Test Raycast extension
+      run: pnpm --filter hanzo-ai test
+
+    - name: Test JupyterLab extension
+      run: pnpm --filter @hanzo/jupyter test
+
+    - name: Test GitLab integration
+      run: pnpm --filter @hanzo/gitlab test
+
+    - name: Test Desktop app (frontend)
+      run: pnpm --filter @hanzo/desktop test
+
+    - name: Test Procore (construction)
+      run: pnpm --filter @hanzo/procore test
+
+    - name: Test QuickBooks (finance)
+      run: pnpm --filter @hanzo/quickbooks test
+
+    - name: Test Epic (SMART-on-FHIR)
+      run: pnpm --filter @hanzo/epic test
+
+    - name: Test Canvas LMS (education)
+      run: pnpm --filter @hanzo/canvas-lms test
+
+    - name: Test Workday (HR)
+      run: pnpm --filter @hanzo/workday test
+
+    - name: Test iManage (legal DMS)
+      run: pnpm --filter @hanzo/imanage test
+
+    - name: Test cards (shared card-builder)
+      run: pnpm --filter @hanzo/cards test
+
+    - name: Test Slack app
+      run: pnpm --filter @hanzo/slack test
+
+    - name: Test Teams app
+      run: pnpm --filter @hanzo/teams test
+
+    - name: Test Zoom + Meet
+      run: pnpm --filter @hanzo/meetings test
+
    - name: Test tools package
      run: pnpm --filter @hanzo/cli-tools test

@@ -1,5 +1,12 @@
 name: Publish

+# Store-publish (Chrome Web Store, Firefox AMO, VS Code, Open VSX, JetBrains) and
+# every store credential have moved to the native pipeline on Hanzo Git:
+#   .gitea/workflows/publish.yml — reads creds from KMS (deploy/kms/…), NOT GitHub.
+# GitHub retains only: build + the downloadable GitHub Release (mirror
+# distribution), and the live npm publish (interim — migrates to native once the
+# KMS NPM_TOKEN is seeded and the native run is verified green).
+
 on:
  push:
    tags:
@@ -17,25 +24,16 @@ permissions:
  contents: write

 jobs:
-  # ─── Check available secrets ───
+  # ─── npm publish gate (the one store credential still on GitHub) ───
  secrets:
-    name: Load KMS Secrets
+    name: Check npm token
    runs-on: hanzo-build-linux-amd64
    outputs:
-      has-chrome: ${{ steps.check.outputs.has-chrome }}
-      has-firefox: ${{ steps.check.outputs.has-firefox }}
-      has-vsce: ${{ steps.check.outputs.has-vsce }}
      has-npm: ${{ steps.check.outputs.has-npm }}
-      has-jetbrains: ${{ steps.check.outputs.has-jetbrains }}
    steps:
-    - name: Check available secrets
+    - name: Check npm token
      id: check
-      run: |
-        echo "has-chrome=${{ secrets.CHROME_EXTENSION_ID != '' }}" >> $GITHUB_OUTPUT
-        echo "has-firefox=${{ secrets.AMO_API_KEY != '' }}" >> $GITHUB_OUTPUT
-        echo "has-vsce=${{ secrets.VSCE_PAT != '' }}" >> $GITHUB_OUTPUT
-        echo "has-npm=${{ secrets.NPM_TOKEN != '' }}" >> $GITHUB_OUTPUT
-        echo "has-jetbrains=${{ secrets.JETBRAINS_TOKEN != '' }}" >> $GITHUB_OUTPUT
+      run: echo "has-npm=${{ secrets.NPM_TOKEN != '' }}" >> $GITHUB_OUTPUT

  # ─── Chrome + Firefox ───
  browser:
@@ -84,40 +82,6 @@ jobs:
      run: npx web-ext lint --source-dir dist/browser-extension/firefox
      continue-on-error: true

-    - name: Publish to Chrome Web Store
-      if: needs.secrets.outputs.has-chrome == 'true'
-      working-directory: packages/browser
-      run: |
-        ACCESS_TOKEN=$(curl -s -X POST "https://oauth2.googleapis.com/token" \
-          -d "client_id=${{ secrets.CHROME_CLIENT_ID }}" \
-          -d "client_secret=${{ secrets.CHROME_CLIENT_SECRET }}" \
-          -d "refresh_token=${{ secrets.CHROME_REFRESH_TOKEN }}" \
-          -d "grant_type=refresh_token" | jq -r '.access_token')
-        VERSION=$(node -p "require('./package.json').version")
-        curl -sf -X PUT \
-          "https://www.googleapis.com/upload/chromewebstore/v1.1/items/${{ secrets.CHROME_EXTENSION_ID }}" \
-          -H "Authorization: Bearer $ACCESS_TOKEN" \
-          -H "x-goog-api-version: 2" \
-          -T dist/hanzo-ai-chrome-v${VERSION}.zip
-        curl -sf -X POST \
-          "https://www.googleapis.com/chromewebstore/v1.1/items/${{ secrets.CHROME_EXTENSION_ID }}/publish" \
-          -H "Authorization: Bearer $ACCESS_TOKEN" \
-          -H "x-goog-api-version: 2" \
-          -H "Content-Length: 0"
-      continue-on-error: true
-
-    - name: Publish to Firefox Add-ons
-      if: needs.secrets.outputs.has-firefox == 'true'
-      working-directory: packages/browser
-      run: |
-        npx web-ext sign \
-          --source-dir dist/browser-extension/firefox \
-          --api-key "${{ secrets.AMO_API_KEY }}" \
-          --api-secret "${{ secrets.AMO_API_SECRET }}" \
-          --channel listed \
-          --id "hanzo-ai@hanzo.ai"
-      continue-on-error: true
-
  # ─── Safari (macOS + iOS) ───
  safari:
    name: Safari (macOS + iOS)
@@ -161,13 +125,15 @@ jobs:
      run: |
        VERSION=${GITHUB_REF_NAME#v}
        cd dist
-        # Prefer the built .app products; fall back to the Xcode source project.
-        APPS=$(find safari-build-macos safari-build-ios -name '*.app' -type d 2>/dev/null || true)
-        if [ -n "$APPS" ]; then
-          zip -r -y "/tmp/hanzo-ai-safari-v${VERSION}.zip" $APPS
-        else
-          zip -r "/tmp/hanzo-ai-safari-v${VERSION}.zip" "safari/Hanzo AI"
+        # Zip the whole Safari output tree: the Xcode project (build.js always
+        # emits dist/safari — a developer opens it to build+sign+sideload) plus any
+        # built .app products. Guard so a `zip` exit code (e.g. 12 "nothing to do")
+        # never blanks the release asset; only skip if there is genuinely nothing.
+        TARGETS=$(ls -d safari safari-build-macos safari-build-ios 2>/dev/null || true)
+        if [ -n "$TARGETS" ]; then
+          zip -r -y "/tmp/hanzo-ai-safari-v${VERSION}.zip" $TARGETS || true
        fi
+        ls -la /tmp/hanzo-ai-safari-v*.zip 2>/dev/null || echo "no Safari output produced"
      continue-on-error: true

    - name: Upload Safari bundle
@@ -226,19 +192,7 @@ jobs:
        name: hanzo-ai-ide
        path: packages/vscode/release-assets/*

-    - name: Publish to VS Code Marketplace
-      if: needs.secrets.outputs.has-vsce == 'true'
-      working-directory: packages/vscode
-      run: vsce publish -p ${{ secrets.VSCE_PAT }}
-      continue-on-error: true
-
-    - name: Publish to Open VSX
-      if: needs.secrets.outputs.has-vsce == 'true'
-      working-directory: packages/vscode
-      run: ovsx publish *.vsix -p ${{ secrets.OVSX_PAT }}
-      continue-on-error: true
-
-  # ─── npm (@hanzo/mcp) ───
+  # ─── npm (all @hanzo/* workspace packages) ───
  npm:
    name: npm
    runs-on: hanzo-build-linux-amd64
@@ -253,13 +207,37 @@ jobs:
        cache: 'pnpm'
        registry-url: 'https://registry.npmjs.org'
    - run: pnpm install --frozen-lockfile
-    - run: pnpm --filter @hanzo/mcp run build
-    - name: Publish @hanzo/mcp
-      working-directory: packages/mcp
-      run: npm publish --access public
+
+    # Shared libraries first: their consumers (slack, teams) import the built
+    # dist at publish time, so @hanzo/cards must exist before the rest build.
+    - name: Build shared libraries
+      run: pnpm --filter @hanzo/cards build
+
+    # Build everything with a build script. Guarded with `|| true` so a package
+    # whose toolchain is absent on the runner (jupyter→jupyterlab, desktop→cargo)
+    # cannot abort the publish of the rest.
+    - name: Build all packages
+      run: pnpm -r --if-present run build || true
+
+    # Recursive publish: skips private (root, apps/site), skips versions already
+    # on npm (e.g. @hanzo/mcp), rewrites workspace:* → the real version, and
+    # publishes in topological order so @hanzo/cards lands before its consumers.
+    # --ignore-scripts is required: raycast (hanzo-ai) and vscode (hanzo-ide)
+    # define a `publish` lifecycle script targeting their own stores (Raycast /
+    # VS Marketplace); without this flag those scripts run mid-publish, fail, and
+    # abort every package after them. Builds already ran above, so no publish-time
+    # script is needed. `|| true` keeps one bad package from blocking the rest.
+    - name: Publish all
+      run: |
+        # setup-node writes a ${NODE_AUTH_TOKEN}-templated .npmrc that `npm` expands
+        # but `pnpm publish` does not reliably read — write the token literally so
+        # pnpm authenticates (a 404 on PUT is npm's obscured "unauthenticated").
+        echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" >> .npmrc
+        echo "@hanzo:registry=https://registry.npmjs.org/" >> .npmrc
+        npm whoami || echo "::warning::npm whoami failed — NPM_TOKEN invalid or lacks @hanzo publish rights"
+        pnpm -r publish --access public --no-git-checks --ignore-scripts --report-summary || true
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      continue-on-error: true

  # ─── JetBrains Marketplace ───
  jetbrains:
@@ -292,14 +270,6 @@ jobs:
        name: hanzo-ai-jetbrains
        path: /tmp/hanzo-ai-jetbrains-v*.zip

-    - name: Publish to JetBrains Marketplace
-      if: needs.secrets.outputs.has-jetbrains == 'true'
-      working-directory: packages/jetbrains
-      run: ./gradlew publishPlugin
-      env:
-        PUBLISH_TOKEN: ${{ secrets.JETBRAINS_TOKEN }}
-      continue-on-error: true
-
  # ─── Microsoft Office add-in (Word / Excel / PowerPoint) ───
  office:
    name: Office Add-in
@@ -326,11 +296,298 @@ jobs:
        name: hanzo-ai-office
        path: /tmp/hanzo-ai-office-v*.zip

+  # ─── Microsoft Outlook mail add-in ───
+  outlook:
+    name: Outlook Add-in
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - run: pnpm install --frozen-lockfile
+
+    - name: Build + package
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        pnpm --filter @hanzo/outlook-addin build
+        cd packages/outlook/dist && npx --yes bestzip "/tmp/hanzo-ai-outlook-v${VERSION}.zip" .
+
+    - name: Upload Outlook add-in
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-outlook
+        path: /tmp/hanzo-ai-outlook-v*.zip
+
+  # ─── Figma plugin ───
+  figma:
+    name: Figma Plugin
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - run: pnpm install --frozen-lockfile
+
+    - name: Build + package
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        pnpm --filter @hanzo/cards build
+        pnpm --filter @hanzo/figma build
+        # dist/ = manifest.json + code.js + ui.html. Import via
+        # Figma → Plugins → Development → Import plugin from manifest.
+        cd packages/figma/dist && npx --yes bestzip "/tmp/hanzo-ai-figma-v${VERSION}.zip" .
+
+    - name: Upload Figma plugin
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-figma
+        path: /tmp/hanzo-ai-figma-v*.zip
+
+  # ─── Sketch plugin ───
+  sketch:
+    name: Sketch Plugin
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - run: pnpm install --frozen-lockfile
+
+    - name: Build + package
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        pnpm --filter @hanzo/cards build
+        pnpm --filter @hanzo/sketch build
+        # dist/ contains the "Hanzo AI.sketchplugin" bundle; zip from dist so the
+        # bundle sits at the archive root (double-click to install into Sketch).
+        cd packages/sketch/dist && npx --yes bestzip "/tmp/hanzo-ai-sketch-v${VERSION}.zip" .
+
+    - name: Upload Sketch plugin
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-sketch
+        path: /tmp/hanzo-ai-sketch-v*.zip
+
+  # ─── Microsoft Teams app ───
+  teams:
+    name: Teams App
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - run: pnpm install --frozen-lockfile
+
+    - name: Build + package
+      env:
+        # The manifest builder substitutes the bot app id into the sideloadable
+        # package and errors on unset placeholders. Use the registered bot id when
+        # available; otherwise a nil-GUID placeholder so the release asset always
+        # builds (sideloaders replace it with their own Azure Bot registration).
+        MICROSOFT_APP_ID: ${{ secrets.MICROSOFT_APP_ID != '' && secrets.MICROSOFT_APP_ID || '00000000-0000-0000-0000-000000000000' }}
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        pnpm --filter @hanzo/cards build
+        pnpm --filter @hanzo/teams build
+        # The teams `package` script emits dist/hanzo-teams.zip (manifest + icons).
+        pnpm --filter @hanzo/teams package
+        cp packages/teams/dist/hanzo-teams.zip "/tmp/hanzo-ai-teams-v${VERSION}.zip"
+
+    - name: Upload Teams app
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-teams
+        path: /tmp/hanzo-ai-teams-v*.zip
+
+  # ─── Zendesk Support app ───
+  zendesk:
+    name: Zendesk App
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - run: pnpm install --frozen-lockfile
+
+    - name: Build + package
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        pnpm --filter @hanzo/cards build
+        pnpm --filter @hanzo/zendesk build
+        # dist/ is the ZAF v2 app (manifest.json + assets/ + translations/).
+        cd packages/zendesk/dist && npx --yes bestzip "/tmp/hanzo-ai-zendesk-v${VERSION}.zip" .
+
+    - name: Upload Zendesk app
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-zendesk
+        path: /tmp/hanzo-ai-zendesk-v*.zip
+
+  # ─── Desktop app — per-OS Tauri installers ───
+  desktop:
+    name: Desktop (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    needs: secrets
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest, ubuntu-latest]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - uses: dtolnay/rust-toolchain@stable
+
+    - name: Install Tauri Linux deps
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          libwebkit2gtk-4.1-dev libgtk-3-dev \
+          libayatana-appindicator3-dev librsvg2-dev patchelf
+
+    - run: pnpm install
+
+    - name: Build frontend
+      run: pnpm --filter @hanzo/desktop build
+
+    - name: Build Tauri installers
+      run: pnpm --filter @hanzo/desktop tauri:build
+      continue-on-error: true
+
+    # Collect the native installer(s) and rename to a stable, per-OS release name.
+    # Signing/notarization is future work — a per-OS failure must not block others.
+    - name: Package for release (macOS)
+      if: matrix.os == 'macos-latest'
+      continue-on-error: true
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        mkdir -p desktop-artifacts
+        DMG=$(ls packages/desktop/src-tauri/target/release/bundle/dmg/*.dmg 2>/dev/null | head -1)
+        if [ -n "$DMG" ]; then cp "$DMG" "desktop-artifacts/hanzo-ai-desktop-macos-v${VERSION}.dmg"; fi
+        ls -la desktop-artifacts/ || echo "no macOS installer produced"
+
+    - name: Package for release (Windows)
+      if: matrix.os == 'windows-latest'
+      continue-on-error: true
+      shell: bash
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        mkdir -p desktop-artifacts
+        MSI=$(ls packages/desktop/src-tauri/target/release/bundle/msi/*.msi 2>/dev/null | head -1)
+        EXE=$(ls packages/desktop/src-tauri/target/release/bundle/nsis/*.exe 2>/dev/null | head -1)
+        if [ -n "$MSI" ]; then cp "$MSI" "desktop-artifacts/hanzo-ai-desktop-windows-v${VERSION}.msi"; fi
+        if [ -n "$EXE" ]; then cp "$EXE" "desktop-artifacts/hanzo-ai-desktop-windows-v${VERSION}.exe"; fi
+        ls -la desktop-artifacts/ || echo "no Windows installer produced"
+
+    - name: Package for release (Linux)
+      if: matrix.os == 'ubuntu-latest'
+      continue-on-error: true
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        mkdir -p desktop-artifacts
+        APPIMAGE=$(ls packages/desktop/src-tauri/target/release/bundle/appimage/*.AppImage 2>/dev/null | head -1)
+        DEB=$(ls packages/desktop/src-tauri/target/release/bundle/deb/*.deb 2>/dev/null | head -1)
+        if [ -n "$APPIMAGE" ]; then cp "$APPIMAGE" "desktop-artifacts/hanzo-ai-desktop-linux-v${VERSION}.AppImage"; fi
+        if [ -n "$DEB" ]; then cp "$DEB" "desktop-artifacts/hanzo-ai-desktop-linux-v${VERSION}.deb"; fi
+        ls -la desktop-artifacts/ || echo "no Linux installer produced"
+
+    - name: Upload Desktop installer
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-desktop-${{ runner.os }}
+        path: desktop-artifacts/*
+        if-no-files-found: ignore
+      continue-on-error: true
+
+  # ─── JupyterLab extension (Python wheel) ───
+  jupyter:
+    name: JupyterLab Extension
+    runs-on: hanzo-build-linux-amd64
+    needs: secrets
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - run: pnpm install --frozen-lockfile
+
+    # JupyterLab provides `jlpm` (the yarn wrapper the labextension build calls) and
+    # the `build` frontend. Install it BEFORE the labextension build, else
+    # `jlpm build:lib` fails with `jlpm: not found` and skips the whole release.
+    - name: Install JupyterLab toolchain
+      continue-on-error: true
+      run: python -m pip install --upgrade jupyterlab build
+
+    # Build the PROD labextension via pnpm (NOT jlpm). jlpm is yarn, which refuses to
+    # `install` inside this pnpm monorepo ("not part of the project"). Running the
+    # scripts through pnpm uses the already-installed node_modules and produces
+    # hanzo_jupyter/labextension/static/style.js — the hook's skip-if-exists target,
+    # so the wheel build below skips jlpm entirely.
+    - name: Build labextension (prod, via pnpm)
+      continue-on-error: true
+      run: |
+        pnpm --filter @hanzo/jupyter run build:lib:prod
+        pnpm --filter @hanzo/jupyter run build:labextension
+
+    - name: Build wheel
+      continue-on-error: true
+      working-directory: packages/jupyter
+      run: |
+        VERSION=${GITHUB_REF_NAME#v}
+        # skip-if-exists (hanzo_jupyter/labextension/static/style.js) is satisfied by
+        # the prod labextension above, so hatch-jupyter-builder does NOT invoke jlpm.
+        python -m build --wheel
+        mkdir -p /tmp/jupyter
+        WHL=$(ls dist/hanzo_jupyter-*.whl dist/hanzo_ai_jupyter-*.whl 2>/dev/null | head -1)
+        if [ -n "$WHL" ]; then
+          # Rename to the tag version so the advertised release link resolves even
+          # if pyproject's version has not been synced to the tag.
+          cp "$WHL" "/tmp/jupyter/hanzo_jupyter-${VERSION}-py3-none-any.whl"
+        fi
+        ls -la /tmp/jupyter/ || echo "no wheel produced"
+
+    - name: Upload JupyterLab wheel
+      uses: actions/upload-artifact@v4
+      with:
+        name: hanzo-ai-jupyter
+        path: /tmp/jupyter/*.whl
+        if-no-files-found: ignore
+      continue-on-error: true
+
  # ─── GitHub Release with downloadable artifacts ───
  release:
    name: GitHub Release
    runs-on: hanzo-build-linux-amd64
-    needs: [browser, safari, vscode, jetbrains, office]
+    needs: [browser, safari, vscode, jetbrains, office, outlook, figma, sketch, teams, zendesk, desktop, jupyter]
    if: startsWith(github.ref, 'refs/tags/v')
    steps:
    - uses: actions/checkout@v4
@@ -364,6 +621,7 @@ jobs:
          | App | Platform | Download |
          |-----|----------|----------|
          | **Word · Excel · PowerPoint** | Windows / macOS / Web / iPad | [`hanzo-ai-office-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-office-v${{ steps.version.outputs.version }}.zip) |
+          | **Outlook** | Windows / macOS / Web | [`hanzo-ai-outlook-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-outlook-v${{ steps.version.outputs.version }}.zip) |

          > Office: unzip and sideload `manifest.xml` via the M365 admin center, or Insert → Add-ins → Upload My Add-in.

@@ -379,6 +637,44 @@ jobs:
          > Chrome zip also works for Brave, Opera, Vivaldi, Arc.
          > Cursor, Windsurf, and Antigravity use the VS Code VSIX format.

+          ## Design Tools
+
+          | App | Platform | Download |
+          |-----|----------|----------|
+          | **Figma** | Windows / macOS / Web | [`hanzo-ai-figma-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-figma-v${{ steps.version.outputs.version }}.zip) |
+          | **Sketch** | macOS | [`hanzo-ai-sketch-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-sketch-v${{ steps.version.outputs.version }}.zip) |
+
+          > Figma: unzip and import `manifest.json` via Figma → Plugins → Development → Import plugin from manifest.
+          > Sketch: unzip and double-click `Hanzo AI.sketchplugin`.
+
+          ## Team Apps
+
+          | App | Platform | Download |
+          |-----|----------|----------|
+          | **Microsoft Teams** | Windows / macOS / Web | [`hanzo-ai-teams-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-teams-v${{ steps.version.outputs.version }}.zip) |
+          | **Zendesk** | Web | [`hanzo-ai-zendesk-v${{ steps.version.outputs.version }}.zip`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-zendesk-v${{ steps.version.outputs.version }}.zip) |
+
+          > Teams: sideload the zip via Teams → Apps → Manage your apps → Upload an app. Set your own Azure Bot app id before publishing.
+          > Zendesk: upload the zip via the Zendesk Admin Center → Apps and integrations → Upload private app.
+
+          ## Desktop App
+
+          | OS | Format | Download |
+          |----|--------|----------|
+          | **macOS** | `.dmg` | [`hanzo-ai-desktop-macos-v${{ steps.version.outputs.version }}.dmg`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-desktop-macos-v${{ steps.version.outputs.version }}.dmg) |
+          | **Windows** | `.msi` / `.exe` | [`hanzo-ai-desktop-windows-v${{ steps.version.outputs.version }}.msi`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-desktop-windows-v${{ steps.version.outputs.version }}.msi) · [`.exe`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-desktop-windows-v${{ steps.version.outputs.version }}.exe) |
+          | **Linux** | `.AppImage` / `.deb` | [`hanzo-ai-desktop-linux-v${{ steps.version.outputs.version }}.AppImage`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-desktop-linux-v${{ steps.version.outputs.version }}.AppImage) · [`.deb`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo-ai-desktop-linux-v${{ steps.version.outputs.version }}.deb) |
+
+          > Desktop installers are unsigned for now — macOS: right-click → Open; Windows: "More info" → Run anyway.
+
+          ## Data Science
+
+          | App | Platform | Download |
+          |-----|----------|----------|
+          | **JupyterLab** | Windows / macOS / Linux | [`hanzo_jupyter-${{ steps.version.outputs.version }}-py3-none-any.whl`](https://github.com/hanzoai/extension/releases/download/${{ github.ref_name }}/hanzo_jupyter-${{ steps.version.outputs.version }}-py3-none-any.whl) |
+
+          > Jupyter: `pip install hanzo_jupyter-*.whl` then restart JupyterLab.
+
          **Install**: `code --install-extension hanzo-ai-vscode-v${{ steps.version.outputs.version }}.vsix`
          **Antigravity**: `antigravity --install-extension hanzo-ai-antigravity-v${{ steps.version.outputs.version }}.vsix`
        files: |
@@ -386,4 +682,11 @@ jobs:
          artifacts/hanzo-ai-ide/*
          artifacts/hanzo-ai-jetbrains/*
          artifacts/hanzo-ai-office/*
+          artifacts/hanzo-ai-outlook/*
          artifacts/hanzo-ai-safari/*
+          artifacts/hanzo-ai-figma/*
+          artifacts/hanzo-ai-sketch/*
+          artifacts/hanzo-ai-teams/*
+          artifacts/hanzo-ai-zendesk/*
+          artifacts/hanzo-ai-desktop-*/*
+          artifacts/hanzo-ai-jupyter/*
@@ -0,0 +1,35 @@
+# Mirror GitHub → Hanzo Git (git.hanzo.ai) — the ONLY thing GitHub does as a
+# system of record. Hanzo Git is the source forge; its act_runners fire the
+# native pipeline (.gitea/workflows/*). GitHub is a public mirror.
+#
+# Credential: HANZO_GIT_TOKEN — a low-privilege Hanzo-Git push token, the ONE
+# secret GitHub still holds. It is NOT a store/publish credential (those live in
+# KMS only). Absent the token this no-ops with a warning, so it never blocks a
+# push before the operator seeds it. Alternatively the operator enables Gitea's
+# native pull-mirror server-side and this workflow becomes unnecessary.
+name: sync
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  mirror:
+    runs-on: hanzo-build-linux-amd64
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push to git.hanzo.ai
+        env:
+          HANZO_GIT_TOKEN: ${{ secrets.HANZO_GIT_TOKEN }}
+        run: |
+          if [ -z "$HANZO_GIT_TOKEN" ]; then
+            echo "::warning::HANZO_GIT_TOKEN unset — mirror skipped. Seed it (or enable Gitea pull-mirror) to activate the native forge."
+            exit 0
+          fi
+          git push --prune "https://x-access-token:${HANZO_GIT_TOKEN}@git.hanzo.ai/hanzoai/extension.git" \
+            "+refs/remotes/origin/main:refs/heads/main" "+refs/tags/*:refs/tags/*"
@@ -65,3 +65,4 @@ build/
 .next/
 *.log
 tmp/
+.npmrc
@@ -0,0 +1,49 @@
+# Native CI — Hanzo Git act_runners (label hanzo-build-linux-amd64).
+# amd64 test + build gate; mirrors the amd64 lanes of .github/workflows/ci.yml.
+# The macOS (Safari) and cross-platform Playwright matrix stay on GitHub-hosted
+# runners until native macOS/Windows act_runners are green
+# (runners-act-migration.md Phase 2). act_runner reads this unmodified;
+# GitHub.com ignores .hanzo/workflows, so the GitHub release lanes are untouched.
+name: ci
+
+on:
+  push:
+    branches: [main, dev]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: hanzo-build-linux-amd64
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+
+      # Shared workspace lib first — consumers import its built dist/.
+      - run: pnpm --filter @hanzo/cards build
+      - run: pnpm --filter @hanzo/browser-extension test
+      - run: pnpm --filter @hanzo/aci test
+      - run: pnpm --filter @hanzo/auth test
+
+  build:
+    runs-on: hanzo-build-linux-amd64
+    container: node:22-bookworm
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+
+      - name: Build browser extension
+        working-directory: packages/browser
+        run: node src/build.js
+
+      - name: Check bundle budgets
+        working-directory: packages/browser
+        run: |
+          [ -f dist/browser-extension/background.js ] || node src/build.js
+          pnpm run check:bundle-budget
+        continue-on-error: true
@@ -0,0 +1,102 @@
+# Native store-publish — Hanzo Git act_runner (label hanzo-build-linux-amd64).
+# This is the SYSTEM OF RECORD for publishing the browser extension to the
+# Chrome Web Store + Firefox AMO, and for the npm package. GitHub only mirrors.
+#
+# Secrets model — KMS ONLY. The single bootstrap credential is the KMS machine
+# identity (KMS_CLIENT_ID / KMS_CLIENT_SECRET, a git.hanzo.ai Actions secret).
+# Every store credential is pulled from KMS at publish time
+# (org `hanzo`, env `prod`, path `/extension-publish` — see
+# deploy/kms/extension-publish-kms-sync.yaml). No CWS/AMO/npm secret is ever
+# stored in GitHub or Gitea Actions secrets.
+#
+# amd64/Linux only. Safari (macOS) + Windows desktop stay on GitHub-hosted
+# runners until native macOS/Windows act_runners are green
+# (runners-act-migration.md Phase 2).
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: hanzo-build-linux-amd64
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Tools (jq, pnpm)
+        run: |
+          apt-get update && apt-get install -y --no-install-recommends jq curl
+          corepack enable
+      - run: pnpm install --frozen-lockfile
+
+      # ── The ONE secret hop: KMS machine identity → store creds ──
+      # Login once, read each key from hanzo:/extension-publish, mask + export.
+      # A missing key exports empty; each publish step below gates on its creds,
+      # so partial provisioning publishes exactly what KMS has.
+      - name: Load publish secrets from KMS
+        env:
+          KMS_CLIENT_ID: ${{ secrets.KMS_CLIENT_ID }}
+          KMS_CLIENT_SECRET: ${{ secrets.KMS_CLIENT_SECRET }}
+        run: |
+          if [ -z "$KMS_CLIENT_ID" ] || [ -z "$KMS_CLIENT_SECRET" ]; then
+            echo "::warning::KMS machine identity absent — cannot pull publish creds. Seed KMS_CLIENT_ID/SECRET as git.hanzo.ai Actions secrets."
+            exit 0
+          fi
+          KMS=https://kms.hanzo.ai; ORG=hanzo; ENVN=prod; P=extension-publish
+          TOKEN=$(curl -sf "$KMS/v1/kms/auth/login" -H 'Content-Type: application/json' \
+            -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r .accessToken)
+          [ -n "$TOKEN" ] && [ "$TOKEN" != null ] || { echo "::error::KMS login failed"; exit 1; }
+          for KEY in CHROME_EXTENSION_ID CHROME_CLIENT_ID CHROME_CLIENT_SECRET CHROME_REFRESH_TOKEN AMO_API_KEY AMO_API_SECRET NPM_TOKEN; do
+            VAL=$(curl -sf "$KMS/v1/kms/orgs/$ORG/secrets/$P/$KEY?env=$ENVN" \
+              -H "Authorization: Bearer $TOKEN" | jq -r '.secret.value // empty')
+            if [ -n "$VAL" ]; then echo "::add-mask::$VAL"; fi
+            echo "$KEY=$VAL" >> "$GITHUB_ENV"
+          done
+
+      - name: Build browser extension
+        working-directory: packages/browser
+        run: node src/build.js
+
+      - name: Package (web-ext — no zip binary on the runner)
+        working-directory: packages/browser
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          npx web-ext build --source-dir dist/browser-extension/chrome  --artifacts-dir dist --filename hanzo-ai-chrome-v${VERSION}.zip  --overwrite-dest
+          npx web-ext build --source-dir dist/browser-extension/firefox --artifacts-dir dist --filename hanzo-ai-firefox-v${VERSION}.zip --overwrite-dest
+
+      - name: Publish to Chrome Web Store
+        if: env.CHROME_EXTENSION_ID != ''
+        working-directory: packages/browser
+        run: |
+          ACCESS_TOKEN=$(curl -s -X POST "https://oauth2.googleapis.com/token" \
+            -d "client_id=$CHROME_CLIENT_ID" -d "client_secret=$CHROME_CLIENT_SECRET" \
+            -d "refresh_token=$CHROME_REFRESH_TOKEN" -d "grant_type=refresh_token" | jq -r '.access_token')
+          VERSION=$(node -p "require('./package.json').version")
+          curl -sf -X PUT "https://www.googleapis.com/upload/chromewebstore/v1.1/items/$CHROME_EXTENSION_ID" \
+            -H "Authorization: Bearer $ACCESS_TOKEN" -H "x-goog-api-version: 2" \
+            -T dist/hanzo-ai-chrome-v${VERSION}.zip
+          curl -sf -X POST "https://www.googleapis.com/chromewebstore/v1.1/items/$CHROME_EXTENSION_ID/publish" \
+            -H "Authorization: Bearer $ACCESS_TOKEN" -H "x-goog-api-version: 2" -H "Content-Length: 0"
+
+      - name: Publish to Firefox Add-ons
+        if: env.AMO_API_KEY != ''
+        working-directory: packages/browser
+        run: |
+          npx web-ext sign --source-dir dist/browser-extension/firefox \
+            --api-key "$AMO_API_KEY" --api-secret "$AMO_API_SECRET" \
+            --channel listed --id "hanzo-ai@hanzo.ai"
+
+      # npm — canonical home is here. The .github npm job stays live until this
+      # runs green (KMS NPM_TOKEN seeded), then it is deleted. pnpm publish skips
+      # versions already on npm, so any transition overlap is idempotent.
+      - name: Publish @hanzo/* to npm
+        if: env.NPM_TOKEN != ''
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+          echo "@hanzo:registry=https://registry.npmjs.org/" >> .npmrc
+          pnpm --filter @hanzo/cards build
+          pnpm -r --if-present run build || true
+          pnpm -r publish --access public --no-git-checks --ignore-scripts --report-summary || true
@@ -30,6 +30,19 @@ per-browser manifests come from `zapd install-host` (`zap-proto/zapd`).
 Patch only (X.Y.Z+1), never major. `package.json` is the source of truth; `build.js`
 stamps it into every manifest (chrome/firefox/safari).

+## CI/CD (native — Hanzo Git, KMS, act_runner)
+Git of record is `git.hanzo.ai/hanzoai/extension`; GitHub is a mirror.
+- `.gitea/workflows/*` — native pipeline on `hanzo-build-linux-amd64` act_runners:
+  `ci.yml` (amd64 test + build), `publish.yml` (Chrome Web Store + Firefox AMO + npm).
+- Secrets are **KMS only**. The pipeline logs in with the KMS machine identity
+  (`KMS_CLIENT_ID`/`KMS_CLIENT_SECRET`) and pulls store creds from `hanzo:/extension-publish`
+  (env `prod`). CR: `deploy/kms/extension-publish-kms-sync.yaml`. No store cred in
+  any Actions secret store.
+- `.github/workflows/` mirrors + degrades gracefully: `sync.yml` pushes main+tags to
+  Hanzo Git; `ci.yml`/`cross-platform-e2e.yml` keep the macOS(Safari)/Windows/matrix
+  lanes that still need GitHub-hosted runners; `publish.yml` keeps only the GitHub
+  Release + the interim npm publish (store-publish removed → native). See PUBLISHING.md.
+
 ## Cross-platform — WXT migration (canonical plan, not yet executed)

 One WebExtension codebase, every engine. **WXT** = build/SDK layer (build matrix,
@@ -1,33 +1,48 @@
 # Publishing Hanzo Extensions

-This document describes how to publish Hanzo extensions to various marketplaces.
+Publishing is NATIVE: it runs on Hanzo Git (`git.hanzo.ai`) act_runners, and
+every store credential lives in Hanzo KMS. GitHub only mirrors the repo.

-## Required Secrets
+## Topology (one way)

-Add these secrets to your GitHub repository settings:
+- **Git of record:** `git.hanzo.ai/hanzoai/extension`. GitHub is a public
+  mirror; `.github/workflows/sync.yml` pushes `main` + tags to Hanzo Git.
+- **CI/CD:** `.gitea/workflows/*` on `hanzo-build-linux-amd64` act_runners —
+  `ci.yml` (test + build) and `publish.yml` (Chrome Web Store + Firefox AMO + npm).
+- **Secrets — KMS ONLY.** The native pipeline logs in with the KMS machine
+  identity (`KMS_CLIENT_ID` / `KMS_CLIENT_SECRET`) and pulls store creds from
+  org `hanzo`, env `prod`, path `/extension-publish`
+  (see `deploy/kms/extension-publish-kms-sync.yaml`). No store credential is
+  ever a GitHub or Gitea Actions secret.
+- **amd64/Linux publishes natively.** Safari (macOS) + desktop (Windows) stay on
+  GitHub-hosted runners until native macOS/Windows act_runners are green
+  (`universe/docs/architecture/runners-act-migration.md`).

-| Secret | Description | How to Get |
-|--------|-------------|------------|
-| `VSCE_PAT` | VS Code Marketplace token | [Create PAT](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token) |
-| `OVSX_PAT` | Open VSX Registry token | [Create token](https://open-vsx.org/user-settings/tokens) |
-| `NPM_TOKEN` | npm publish token | `npm token create` or [npm.js tokens](https://www.npmjs.com/settings/~/tokens) |
-| `JETBRAINS_TOKEN` | JetBrains Marketplace token | [Generate token](https://plugins.jetbrains.com/author/me/tokens) |
-| `CERTIFICATE_CHAIN` | JetBrains plugin signing cert | [Plugin signing](https://plugins.jetbrains.com/docs/intellij/plugin-signing.html) |
-| `PRIVATE_KEY` | JetBrains plugin signing key | See above |
-| `PRIVATE_KEY_PASSWORD` | JetBrains key password | See above |
+## KMS keys the operator seeds (path `hanzo:/extension-publish`, env `prod`)
+
+| Key(s) | Store |
+|--------|-------|
+| `CHROME_EXTENSION_ID`, `CHROME_CLIENT_ID`, `CHROME_CLIENT_SECRET`, `CHROME_REFRESH_TOKEN` | Chrome Web Store |
+| `AMO_API_KEY`, `AMO_API_SECRET` | Firefox Add-ons |
+| `NPM_TOKEN` | npm (`@hanzo/*`) |

 ## Publishing Methods

-### Automatic (GitHub Actions)
+### Automatic (native)

-1. Create a GitHub release with a version tag (e.g., `v1.6.0`)
-2. The `publish.yml` workflow will automatically publish to all marketplaces
+Push a `vX.Y.Z` tag. GitHub mirrors it to Hanzo Git, which fires
+`.gitea/workflows/publish.yml`. Or run `workflow_dispatch` on Hanzo Git.

-Or manually trigger:
 ```bash
-gh workflow run publish.yml
+# version lives in packages/browser/package.json (patch only, never major)
+git tag v1.9.35 && git push origin v1.9.35
 ```

+> Interim: the live npm publish still also runs from `.github/workflows/publish.yml`
+> until the KMS `NPM_TOKEN` is seeded and one native `publish.yml` run is verified
+> green; then the GitHub npm job is deleted. `pnpm publish` skips versions already
+> on npm, so the overlap is idempotent.
+
 ### Manual Publishing

 #### VS Code Marketplace
@@ -0,0 +1,68 @@
+# Store-publish credentials for the Hanzo browser extension — KMS is the ONLY home.
+#
+# The native publish pipeline (.gitea/workflows/publish.yml, act_runner on
+# git.hanzo.ai) reads these at publish time. No store credential lives in a
+# GitHub or Gitea Actions secret — the ONLY bootstrap credential is the KMS
+# machine identity (KMS_CLIENT_ID / KMS_CLIENT_SECRET), already provisioned.
+#
+# ── Operator steps (the VALUES are the store-account owner's; not in git) ──
+#   1. KMS (kms.hanzo.ai) → org `hanzo`, env `prod`, project path `/extension-publish`.
+#      Add the keys below. These are the Chrome Web Store + Firefox AMO
+#      credentials — the store-account owner drops the real values here:
+#        CHROME_EXTENSION_ID     Chrome Web Store item id
+#        CHROME_CLIENT_ID        Google OAuth client id (CWS API)
+#        CHROME_CLIENT_SECRET    Google OAuth client secret
+#        CHROME_REFRESH_TOKEN    Google OAuth refresh token
+#        AMO_API_KEY             addons.mozilla.org JWT issuer
+#        AMO_API_SECRET          addons.mozilla.org JWT secret
+#      Optional (same path, if these stores are moved off GitHub too):
+#        VSCE_PAT  OVSX_PAT  JETBRAINS_TOKEN  NPM_TOKEN
+#         kms secret set --project hanzo --env prod --path /extension-publish \
+#           CHROME_EXTENSION_ID "<value>"     # …repeat per key
+#   2. Grant the extension repo's KMS machine identity (the KMS_CLIENT_ID it
+#      already uses) READ on project `hanzo`, path `/extension-publish`.
+#   3. Re-provision KMS_CLIENT_ID / KMS_CLIENT_SECRET as git.hanzo.ai Actions
+#      secrets so the native runner can log in (they exist on GitHub today —
+#      runners-act-migration.md Phase 1.2).
+#
+# Canonical GitOps home is universe/infra/k8s/kms-canonical-crs/hanzo/ (generated
+# by scripts/kms-canonical-v1alpha1-gen.py). This in-repo copy is the extension's
+# declared secret contract — reflect it into universe, do not diverge.
+---
+apiVersion: secrets.lux.network/v1alpha1
+kind: KMSSecret
+metadata:
+  name: extension-publish-kms-sync
+  namespace: hanzo
+  labels:
+    app.kubernetes.io/name: extension
+    app.kubernetes.io/component: kms-secret
+    app.kubernetes.io/part-of: hanzo-universe
+    kms.hanzo.ai/org: hanzo
+    kms.hanzo.ai/env: prod
+spec:
+  hostAPI: http://kms.hanzo.svc
+  resyncInterval: 60
+  authentication:
+    universalAuth:
+      # Shared platform machine identity (same as the other hanzo CRs). The
+      # operator scopes it to read /extension-publish.
+      credentialsRef:
+        secretName: hanzo-platform-iam-creds
+        secretNamespace: hanzo
+      secretsScope:
+        projectSlug: hanzo
+        envSlug: prod
+        secretsPath: /extension-publish
+        keys:
+          - CHROME_EXTENSION_ID
+          - CHROME_CLIENT_ID
+          - CHROME_CLIENT_SECRET
+          - CHROME_REFRESH_TOKEN
+          - AMO_API_KEY
+          - AMO_API_SECRET
+  managedSecretReference:
+    secretName: extension-publish-secrets
+    secretNamespace: hanzo
+    secretType: Opaque
+    creationPolicy: Orphan
@@ -53,9 +53,9 @@ The Hanzo agent automatically detects and uses available LLM providers in this o
   - Access to all models with credits
   - Managed API keys in Hanzo Cloud

-## Complete Model Catalog (OpenRouter + LiteLLM Compatible)
+## Complete Model Catalog

-Hanzo AI provides access to every model available through OpenRouter and LiteLLM, including:
+Hanzo AI provides access to every major model through one API, including:

 - **OpenAI**: O3-Pro, O3, GPT-4o, GPT-4 Turbo, GPT-4, GPT-3.5 Turbo
 - **Anthropic**: Claude 4, Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku
@@ -159,7 +159,7 @@ export OLLAMA_BASE_URL=http://localhost:11434
 ## Why AI Engineers Choose Hanzo AI

 ### 🎯 **The Complete Toolkit**
- **Every Model**: OpenRouter + LiteLLM = access to every AI model
+- **Every Model**: one API across every major provider and our own Zen family
 - **Every Tool**: 4000+ MCP servers for specialized capabilities
 - **Every Provider**: OpenAI, Anthropic, Google, Meta, Mistral, and 50+ more

@@ -300,6 +300,6 @@ Error: Model xyz not available through Hanzo AI
 - **Dashboard**: [iam.hanzo.ai](https://iam.hanzo.ai)
 - **Support**: support@hanzo.ai

-**Hanzo AI is the unified platform for building AI-powered companies.** Access 200+ LLMs (OpenRouter/LiteLLM compatible), 4000+ MCP servers, legendary programmer modes, unlimited memory with vector/graph/relational search, browser automation, and everything you need to supercharge AI development. 
+**Hanzo AI is the unified platform for building AI-powered companies.** Access 200+ models through one API, 4000+ MCP servers, legendary programmer modes, unlimited memory with vector/graph/relational search, browser automation, and everything you need to supercharge AI development. 

 🚀 **[Get Started](https://iam.hanzo.ai)** | 📖 **[View Modes & Features](./HANZO_MODES.md)** | 💬 **[Join Discord](https://discord.gg/hanzoai)**
@@ -1,6 +1,6 @@
 {
  "name": "@hanzo/extension",
-  "version": "1.9.29",
+  "version": "1.9.35",
  "private": true,
  "description": "Hanzo AI Extension",
  "license": "MIT",
@@ -47,5 +47,12 @@
  "homepage": "https://hanzo.ai",
  "bugs": {
    "url": "https://github.com/hanzoai/aci/issues"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
 }
@@ -1,12 +0,0 @@
-Copyright 2025 Hanzo Industries Inc
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -1,236 +0,0 @@
-# @hanzo/ai
-
-The AI Toolkit for TypeScript - AgentKit with Model Context Protocol (MCP) support.
-
-## Features
-
- 🤖 **Multi-Provider Support**: OpenAI, Anthropic, Google, Mistral, Bedrock, Vertex AI, Cohere, and more
- 🔧 **MCP Integration**: Full Model Context Protocol support for tool calling
- 🌐 **Agent Networks**: Create and orchestrate multiple AI agents
- 📊 **Observability**: Built-in telemetry with OpenTelemetry support
- 🔄 **Streaming**: First-class streaming support for all providers
- 📝 **Type Safety**: Full TypeScript support with comprehensive types
- 🎯 **Unified API**: Consistent interface across all providers
-
-## Installation
-
-```bash
-npm install @hanzo/ai
-```
-
-## Quick Start
-
-### Basic Text Generation
-
-```typescript
-import { generateText, openai } from '@hanzo/ai';
-
-const result = await generateText({
-  model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4'),
-  prompt: 'What is the meaning of life?',
-  maxTokens: 500
-});
-
-console.log(result.text);
-```
-
-### Creating an Agent
-
-```typescript
-import { createAgent, anthropic } from '@hanzo/ai';
-
-const agent = createAgent({
-  name: 'Assistant',
-  model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })('claude-3-sonnet'),
-  instructions: 'You are a helpful assistant.',
-  tools: [
-    {
-      name: 'calculate',
-      description: 'Perform mathematical calculations',
-      parameters: {
-        type: 'object',
-        properties: {
-          expression: { type: 'string' }
-        }
-      },
-      handler: async ({ expression }) => {
-        return { result: eval(expression) };
-      }
-    }
-  ]
-});
-
-const response = await agent.run('What is 2 + 2?');
-```
-
-### Agent Networks
-
-```typescript
-import { createNetwork, createAgent, openai, anthropic } from '@hanzo/ai';
-
-const network = createNetwork({
-  agents: [
-    createAgent({
-      name: 'researcher',
-      model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4'),
-      instructions: 'You are a research specialist.'
-    }),
-    createAgent({
-      name: 'writer',
-      model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })('claude-3-sonnet'),
-      instructions: 'You are a creative writer.'
-    })
-  ]
-});
-
-// Agents can collaborate
-const result = await network.run('Research and write a short story about AI');
-```
-
-### Streaming
-
-```typescript
-import { generateStream, google } from '@hanzo/ai';
-
-const stream = await generateStream({
-  model: google({ apiKey: process.env.GOOGLE_API_KEY })('gemini-pro'),
-  prompt: 'Tell me a story',
-  maxTokens: 1000
-});
-
-for await (const chunk of stream) {
-  process.stdout.write(chunk.text);
-}
-```
-
-### Object Generation
-
-```typescript
-import { generateObject, openai } from '@hanzo/ai';
-import { z } from 'zod';
-
-const schema = z.object({
-  name: z.string(),
-  age: z.number(),
-  interests: z.array(z.string())
-});
-
-const result = await generateObject({
-  model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4'),
-  prompt: 'Generate a random person profile',
-  schema
-});
-
-console.log(result.object); // Typed as { name: string, age: number, interests: string[] }
-```
-
-## MCP Support
-
-@hanzo/ai includes full Model Context Protocol support:
-
-```typescript
-import { createAgent } from '@hanzo/ai';
-import { createMCPClient } from '@hanzo/ai/mcp';
-
-// Connect to an MCP server
-const mcpClient = await createMCPClient({
-  command: 'node',
-  args: ['path/to/mcp-server.js']
-});
-
-// Use MCP tools with an agent
-const agent = createAgent({
-  name: 'mcp-agent',
-  model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4'),
-  tools: await mcpClient.getTools()
-});
-```
-
-## Providers
-
-Supported providers with their respective models:
-
- **OpenAI**: GPT-4, GPT-3.5, o1-preview, o1-mini
- **Anthropic**: Claude 3 (Opus, Sonnet, Haiku), Claude 2
- **Google**: Gemini Pro, Gemini Ultra, PaLM
- **Mistral**: Mistral Large, Medium, Small, Mixtral
- **AWS Bedrock**: Access to multiple models
- **Google Vertex AI**: Enterprise Google AI
- **Cohere**: Command, Generate, Embed
- **Hanzo**: Custom Hanzo models
-
-## Telemetry
-
-Built-in telemetry support with OpenTelemetry:
-
-```typescript
-import { createHanzoCloudTelemetry } from '@hanzo/ai/telemetry';
-
-// Initialize telemetry
-const telemetry = createHanzoCloudTelemetry({
-  apiKey: process.env.HANZO_API_KEY,
-  serviceName: 'my-ai-app'
-});
-
-// All AI operations are automatically traced
-```
-
-## Advanced Usage
-
-### Custom Providers
-
-```typescript
-import { createProvider } from '@hanzo/ai';
-
-const customProvider = createProvider({
-  name: 'custom',
-  generateText: async ({ prompt, maxTokens }) => {
-    // Your implementation
-    return { text: 'Response' };
-  }
-});
-```
-
-### Tool Creation
-
-```typescript
-import { createTool } from '@hanzo/ai';
-
-const weatherTool = createTool({
-  name: 'get_weather',
-  description: 'Get current weather for a location',
-  parameters: {
-    type: 'object',
-    properties: {
-      location: { type: 'string' }
-    },
-    required: ['location']
-  },
-  handler: async ({ location }) => {
-    // Implementation
-    return { temperature: 72, condition: 'sunny' };
-  }
-});
-```
-
-### State Management
-
-```typescript
-import { createState } from '@hanzo/ai';
-
-const state = createState({
-  messages: [],
-  context: {}
-});
-
-// Use with agents for conversation memory
-const agent = createAgent({
-  name: 'stateful-agent',
-  model: openai({ apiKey: process.env.OPENAI_API_KEY })('gpt-4'),
-  state
-});
-```
-
-## License
-
-MIT © Hanzo AI
@@ -1,369 +0,0 @@
-# Telemetry & Observability
-
-@hanzo/ai includes comprehensive telemetry and observability features that integrate seamlessly with Hanzo Cloud's monitoring platform.
-
-## Overview
-
-The telemetry system provides:
- Distributed tracing with OpenTelemetry
- Structured logging with Winston
- Metrics collection (counters, gauges, histograms)
- Session tracking
- Error tracking and reporting
- Performance monitoring
-
-## Basic Usage
-
-### Local Telemetry
-
-```typescript
-import { createAgent, Telemetry } from '@hanzo/ai';
-
-// Create a basic telemetry instance
-const telemetry = new Telemetry({
-  serviceName: 'my-ai-service',
-  enabled: true
-});
-
-// Use with agents
-const agent = createAgent({
-  name: 'my-agent',
-  // ... other config
-});
-
-const result = await agent.run({
-  messages: [{ role: 'user', content: 'Hello' }],
-  context: { telemetry }
-});
-```
-
-### Hanzo Cloud Integration
-
-```typescript
-import { createHanzoCloudTelemetry } from '@hanzo/ai/telemetry/hanzo-cloud';
-
-// Initialize Hanzo Cloud telemetry
-const telemetry = createHanzoCloudTelemetry({
-  cloudUrl: 'https://cloud.hanzo.ai',
-  apiKey: process.env.HANZO_CLOUD_API_KEY!,
-  projectId: process.env.HANZO_PROJECT_ID!,
-  environment: 'production',
-  serviceName: 'customer-support-ai',
-  serviceVersion: '1.0.0'
-});
-```
-
-## Features
-
-### Distributed Tracing
-
-Track execution flow across agents and networks:
-
-```typescript
-// Trace a custom operation
-const result = await telemetry.trace(
-  'process_order',
-  async (span) => {
-    span.setAttributes({
-      'order.id': orderId,
-      'order.amount': amount
-    });
-    
-    // Your logic here
-    return processOrder(orderId);
-  },
-  {
-    kind: SpanKind.CLIENT,
-    attributes: {
-      'service.operation': 'order_processing'
-    }
-  }
-);
-```
-
-### Structured Logging
-
-Log with automatic trace context:
-
-```typescript
-telemetry.log('info', 'Processing customer request', {
-  customerId: '12345',
-  requestType: 'support'
-});
-
-telemetry.log('error', 'Failed to process request', {
-  error: error.message,
-  stack: error.stack
-});
-```
-
-### Metrics Collection
-
-Track key performance indicators:
-
-```typescript
-// Counters
-telemetry.increment('api.requests', 1, {
-  endpoint: '/chat',
-  method: 'POST'
-});
-
-// Gauges
-telemetry.gauge('queue.size', queueLength, {
-  queue: 'processing'
-});
-
-// Histograms
-telemetry.histogram('response.time', responseTime, {
-  endpoint: '/chat'
-});
-```
-
-### Agent & Network Metrics
-
-Automatic metrics for agent executions:
-
- `agent.executions` - Count of agent runs
- `agent.execution.duration` - Agent execution time
- `agent.tokens.used` - Token usage per agent
- `tool.executions` - Tool usage statistics
- `network.iterations` - Network iteration count
- `network.execution.duration` - Total network execution time
-
-### Session Tracking
-
-Track related executions:
-
-```typescript
-// Create a session
-const sessionId = telemetry.createSession();
-
-// All subsequent operations will be linked to this session
-const result = await network.run({
-  messages: [...],
-  telemetry
-});
-```
-
-### Error Tracking
-
-Automatic error capture with context:
-
-```typescript
-try {
-  await agent.run({ messages, telemetry });
-} catch (error) {
-  // Errors are automatically recorded with span context
-  telemetry.recordException(error);
-}
-```
-
-## Network Telemetry
-
-Networks provide additional telemetry:
-
-```typescript
-const network = createNetwork({
-  name: 'support_network',
-  agents: [classifier, techSupport, billing],
-  // ...
-});
-
-// Automatic tracking of:
-// - Router decisions
-// - Agent handoffs
-// - State changes
-// - Iteration count
-// - Total execution time
-
-const result = await network.run({
-  messages: [...],
-  telemetry
-});
-```
-
-## MCP Server Telemetry
-
-Track MCP server connections:
-
-```typescript
-// Automatic tracking when MCP servers are connected
-const agent = createAgent({
-  name: 'mcp-agent',
-  mcpServers: [{
-    name: 'file-system',
-    transport: { type: 'stdio', command: 'mcp-fs' }
-  }]
-});
-
-// Metrics tracked:
-// - mcp.connections
-// - mcp.servers.active
-// - mcp.tool.calls
-```
-
-## Best Practices
-
-### 1. Use Structured Attributes
-
-```typescript
-span.setAttributes({
-  'user.id': userId,
-  'user.tier': 'premium',
-  'request.type': 'chat',
-  'request.model': 'gpt-4'
-});
-```
-
-### 2. Create Meaningful Spans
-
-```typescript
-await telemetry.trace('user_request', async () => {
-  await telemetry.trace('validate_input', validateInput);
-  await telemetry.trace('process_with_ai', processAI);
-  await telemetry.trace('format_response', formatResponse);
-});
-```
-
-### 3. Track Business Metrics
-
-```typescript
-// Track business-relevant metrics
-telemetry.increment('revenue.processed', amount, {
-  currency: 'USD',
-  paymentMethod: 'stripe'
-});
-
-telemetry.gauge('customer.satisfaction', score, {
-  surveyType: 'nps'
-});
-```
-
-### 4. Use Session Context
-
-```typescript
-// Link related operations
-const sessionId = telemetry.createSession();
-
-for (const message of conversation) {
-  await handleMessage(message, telemetry);
-}
-```
-
-### 5. Proper Cleanup
-
-```typescript
-// Always flush telemetry before shutdown
-process.on('SIGTERM', async () => {
-  await telemetry.shutdown();
-  process.exit(0);
-});
-```
-
-## Viewing Telemetry Data
-
-### Hanzo Cloud Console
-
-Access your telemetry data at:
- Traces: `https://cloud.hanzo.ai/projects/{projectId}/traces`
- Metrics: `https://cloud.hanzo.ai/projects/{projectId}/metrics`
- Logs: `https://cloud.hanzo.ai/projects/{projectId}/logs`
-
-### Local Development
-
-In development, telemetry outputs to console with structured JSON:
-
-```json
-{
-  "timestamp": "2024-01-15T10:30:45.123Z",
-  "level": "info",
-  "message": "Agent executed",
-  "trace_id": "abc123",
-  "span_id": "def456",
-  "agent": "classifier",
-  "duration": 245,
-  "success": true
-}
-```
-
-## Performance Impact
-
-The telemetry system is designed for minimal overhead:
- Async span processing
- Batched metric collection
- Configurable sampling
- Automatic span pruning
- Efficient memory usage
-
-Disable in performance-critical paths:
-
-```typescript
-const telemetry = new Telemetry({
-  enabled: process.env.NODE_ENV === 'production'
-});
-```
-
-## Troubleshooting
-
-### Missing Traces
-
-Check:
-1. Telemetry is enabled
-2. API key is valid
-3. Network connectivity to Hanzo Cloud
-4. Proper span nesting
-
-### High Memory Usage
-
- Reduce span attributes
- Enable sampling
- Decrease batch size
- Check for span leaks
-
-### Debug Mode
-
-Enable debug logging:
-
-```typescript
-const telemetry = createHanzoCloudTelemetry({
-  // ...
-  logLevel: 'debug'
-});
-```
-
-## Advanced Features
-
-### Custom Span Processors
-
-```typescript
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-
-// Add custom processing
-const processor = new BatchSpanProcessor(customExporter);
-telemetry.addSpanProcessor(processor);
-```
-
-### Context Propagation
-
-```typescript
-// Get trace context for external services
-const headers = telemetry.getTraceContext();
-
-// Make external request with trace context
-await fetch(url, {
-  headers: {
-    ...headers,
-    'Content-Type': 'application/json'
-  }
-});
-```
-
-### Multi-Region Support
-
-```typescript
-const telemetry = createHanzoCloudTelemetry({
-  cloudUrl: process.env.HANZO_CLOUD_URL || 'https://cloud.hanzo.ai',
-  // Auto-detected from environment
-  region: process.env.HANZO_CLOUD_REGION
-});
-```
@@ -1,263 +0,0 @@
-/**
- * Example: Using Hanzo AI with Cloud Telemetry
- * 
- * This example shows how to integrate agents and networks with Hanzo Cloud's
- * observability platform for comprehensive monitoring and debugging.
- */
-
-import { createAgent, createNetwork } from '@hanzo/ai';
-import { createHanzoCloudTelemetry } from '@hanzo/ai/telemetry/hanzo-cloud';
-import { commonTools } from '@hanzo/ai/tools';
-import { OpenAIProvider } from '@hanzo/ai/providers/openai';
-
-// Initialize Hanzo Cloud telemetry
-const telemetry = createHanzoCloudTelemetry({
-  cloudUrl: process.env.HANZO_CLOUD_URL || 'https://cloud.hanzo.ai',
-  apiKey: process.env.HANZO_CLOUD_API_KEY!,
-  projectId: process.env.HANZO_PROJECT_ID!,
-  environment: process.env.NODE_ENV || 'development',
-  serviceName: 'customer-support-ai',
-  serviceVersion: '1.0.0',
-  logLevel: 'info'
-});
-
-// Create a session for tracking related executions
-const sessionId = telemetry.createSession();
-console.log(`Started telemetry session: ${sessionId}`);
-
-// Create agents with telemetry integration
-const classifierAgent = createAgent({
-  name: 'classifier',
-  description: 'Classifies customer inquiries',
-  system: `You are a customer inquiry classifier. Analyze the customer's message and classify it into one of these categories:
-    - technical_support
-    - billing
-    - product_info
-    - complaint
-    - other`,
-  tools: [
-    commonTools.done(),
-    commonTools.handoff()
-  ]
-});
-
-const techSupportAgent = createAgent({
-  name: 'tech_support',
-  description: 'Handles technical support issues',
-  system: 'You are a technical support specialist. Help customers resolve technical issues with our products.',
-  tools: [
-    commonTools.done(),
-    commonTools.askUser()
-  ]
-});
-
-const billingAgent = createAgent({
-  name: 'billing',
-  description: 'Handles billing inquiries',
-  system: 'You are a billing specialist. Help customers with payment, subscription, and invoice questions.',
-  tools: [
-    commonTools.done(),
-    commonTools.remember(),
-    commonTools.recall()
-  ]
-});
-
-// Create network with telemetry
-const supportNetwork = createNetwork({
-  name: 'customer_support',
-  agents: [classifierAgent, techSupportAgent, billingAgent],
-  defaultModel: new OpenAIProvider({
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-4'
-  }),
-  router: (context) => {
-    // First iteration: always start with classifier
-    if (context.iteration === 0) {
-      return context.network.getAgent('classifier');
-    }
-    
-    // Check if classifier has determined the category
-    const category = context.state.get('category');
-    const nextAgent = context.state.get('nextAgent');
-    
-    if (nextAgent) {
-      context.state.delete('nextAgent'); // Clear for next iteration
-      return context.network.getAgent(nextAgent);
-    }
-    
-    if (category === 'technical_support') {
-      return context.network.getAgent('tech_support');
-    } else if (category === 'billing') {
-      return context.network.getAgent('billing');
-    }
-    
-    return undefined; // No more agents to run
-  }
-});
-
-// Example: Process customer inquiry with full telemetry
-async function handleCustomerInquiry(message: string) {
-  // Create a span for the entire operation
-  return telemetry.trace(
-    'customer_inquiry',
-    async (span) => {
-      // Add customer context
-      span.setAttributes({
-        'customer.message.length': message.length,
-        'customer.session.id': sessionId
-      });
-      
-      try {
-        // Log the inquiry
-        telemetry.log('info', 'Processing customer inquiry', {
-          messagePreview: message.substring(0, 100)
-        });
-        
-        // Run the support network
-        const result = await supportNetwork.run({
-          messages: [
-            { role: 'user', content: message }
-          ],
-          telemetry // Pass telemetry instance
-        });
-        
-        // Record success metrics
-        telemetry.increment('customer.inquiries.processed', 1, {
-          status: 'success',
-          category: result.state.category || 'unknown'
-        });
-        
-        // Log the resolution
-        telemetry.log('info', 'Customer inquiry resolved', {
-          iterations: result.iterations,
-          finalAgent: result.history[result.history.length - 1]?.agent,
-          category: result.state.category
-        });
-        
-        return result;
-      } catch (error) {
-        // Record failure metrics
-        telemetry.increment('customer.inquiries.processed', 1, {
-          status: 'error'
-        });
-        
-        telemetry.log('error', 'Failed to process customer inquiry', {
-          error: error instanceof Error ? error.message : String(error)
-        });
-        
-        throw error;
-      }
-    },
-    {
-      attributes: {
-        'inquiry.type': 'customer_support'
-      }
-    }
-  );
-}
-
-// Example: Monitor streaming responses
-async function handleStreamingInquiry(message: string) {
-  const stream = supportNetwork.stream({
-    messages: [
-      { role: 'user', content: message }
-    ],
-    telemetry
-  });
-  
-  let totalTokens = 0;
-  
-  for await (const chunk of stream) {
-    // Track streaming metrics
-    if (chunk.type === 'content') {
-      totalTokens += chunk.content.length;
-      telemetry.gauge('streaming.tokens.current', totalTokens, {
-        agent: chunk.agent
-      });
-    } else if (chunk.type === 'agent:start') {
-      telemetry.log('debug', `Agent ${chunk.agent} started at iteration ${chunk.iteration}`);
-    } else if (chunk.type === 'agent:complete') {
-      telemetry.histogram('agent.streaming.duration', chunk.duration, {
-        agent: chunk.agent
-      });
-    }
-    
-    // Process chunk...
-    console.log(chunk);
-  }
-}
-
-// Example: Batch processing with telemetry
-async function processBatchInquiries(inquiries: string[]) {
-  telemetry.log('info', `Starting batch processing of ${inquiries.length} inquiries`);
-  
-  const results = await Promise.allSettled(
-    inquiries.map((inquiry, index) =>
-      telemetry.trace(
-        `batch_inquiry_${index}`,
-        () => handleCustomerInquiry(inquiry),
-        {
-          attributes: {
-            'batch.index': index,
-            'batch.total': inquiries.length
-          }
-        }
-      )
-    )
-  );
-  
-  // Analyze results
-  const successful = results.filter(r => r.status === 'fulfilled').length;
-  const failed = results.filter(r => r.status === 'rejected').length;
-  
-  telemetry.gauge('batch.success.rate', successful / inquiries.length, {
-    batchSize: inquiries.length
-  });
-  
-  telemetry.log('info', 'Batch processing complete', {
-    total: inquiries.length,
-    successful,
-    failed
-  });
-  
-  return results;
-}
-
-// Example usage
-async function main() {
-  try {
-    // Single inquiry
-    const result = await handleCustomerInquiry(
-      "I'm having trouble logging into my account. It says my password is incorrect but I'm sure it's right."
-    );
-    
-    console.log('Result:', result);
-    
-    // Streaming inquiry
-    await handleStreamingInquiry(
-      "My last bill seems higher than usual. Can you explain the charges?"
-    );
-    
-    // Batch processing
-    const batchResults = await processBatchInquiries([
-      "How do I reset my password?",
-      "What are your business hours?",
-      "I want to cancel my subscription",
-      "The app keeps crashing on startup"
-    ]);
-    
-    console.log(`Processed ${batchResults.length} inquiries`);
-    
-  } finally {
-    // Ensure telemetry is flushed before exit
-    await telemetry.shutdown();
-  }
-}
-
-// Run the example
-if (require.main === module) {
-  main().catch(console.error);
-}
-
-// Export for testing
-export { handleCustomerInquiry, supportNetwork, telemetry };
@@ -1,83 +0,0 @@
-{
-  "name": "@hanzo/ai",
-  "version": "0.1.1",
-  "description": "The AI Toolkit for TypeScript - AgentKit with MCP support",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    },
-    "./server": {
-      "types": "./dist/server/index.d.ts",
-      "import": "./dist/server/index.mjs",
-      "require": "./dist/server/index.js"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.mjs",
-      "require": "./dist/react/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "type-check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.22.0",
-    "eventsource-parser": "^1.0.0",
-    "nanoid": "^5.0.0",
-    "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/resources": "^2.9.0",
-    "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@opentelemetry/instrumentation": "^0.220.0",
-    "@opentelemetry/sdk-trace-node": "^2.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
-    "winston": "^3.11.0"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0",
-    "zod": "^3.0.0 || ^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/react": "^18.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^3.2.6"
-  },
-  "keywords": [
-    "ai",
-    "llm",
-    "agents",
-    "mcp",
-    "typescript",
-    "hanzo"
-  ],
-  "author": "Hanzo AI",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hanzoai/ai.git"
-  }
-}
@@ -1,429 +0,0 @@
-/**
- * Agent implementation with MCP support
- */
-
-import { z } from 'zod';
-import { Tool } from './tool';
-import { MCPServer } from '../mcp/types';
-import { ModelInterface } from '../types';
-import { Telemetry, SpanKind } from '../telemetry';
-import { nanoid } from 'nanoid';
-
-export interface AgentConfig {
-  name: string;
-  description?: string;
-  system?: string;
-  tools?: Tool[];
-  mcpServers?: MCPServer[];
-  model?: ModelInterface;
-  temperature?: number;
-  maxTokens?: number;
-  metadata?: Record<string, any>;
-}
-
-export interface AgentContext {
-  agent: Agent;
-  network?: any; // Will be Network type
-  state?: any;
-  telemetry: Telemetry;
-}
-
-export interface AgentRunOptions {
-  messages: any[];
-  model?: ModelInterface;
-  context?: Partial<AgentContext>;
-  stream?: boolean;
-}
-
-export class Agent {
-  readonly id: string;
-  readonly name: string;
-  readonly description?: string;
-  readonly system?: string;
-  readonly tools: Map<string, Tool>;
-  readonly mcpServers: MCPServer[];
-  readonly model?: ModelInterface;
-  readonly temperature?: number;
-  readonly maxTokens?: number;
-  readonly metadata: Record<string, any>;
-  
-  private mcpTools: Map<string, any> = new Map();
-  private initialized = false;
-  
-  constructor(config: AgentConfig) {
-    this.id = nanoid();
-    this.name = config.name;
-    this.description = config.description;
-    this.system = config.system;
-    this.tools = new Map();
-    this.mcpServers = config.mcpServers || [];
-    this.model = config.model;
-    this.temperature = config.temperature;
-    this.maxTokens = config.maxTokens;
-    this.metadata = config.metadata || {};
-    
-    // Register tools
-    if (config.tools) {
-      for (const tool of config.tools) {
-        this.tools.set(tool.name, tool);
-      }
-    }
-  }
-  
-  async initialize(): Promise<void> {
-    if (this.initialized) return;
-    
-    // Initialize MCP servers
-    for (const server of this.mcpServers) {
-      await this.connectMCPServer(server);
-    }
-    
-    this.initialized = true;
-  }
-  
-  private async connectMCPServer(server: MCPServer): Promise<void> {
-    // Import MCP client dynamically
-    const { MCPClient } = await import('../mcp/client');
-    const client = new MCPClient();
-    
-    await client.connect({
-      name: server.name,
-      transport: server.transport
-    });
-    
-    // Get available tools from MCP server
-    const tools = await client.listTools();
-    
-    // Register MCP tools
-    for (const tool of tools) {
-      this.mcpTools.set(`${server.name}:${tool.name}`, {
-        server,
-        client,
-        tool
-      });
-    }
-  }
-  
-  async run(options: AgentRunOptions): Promise<any> {
-    await this.initialize();
-    
-    const model = options.model || this.model;
-    if (!model) {
-      throw new Error(`No model specified for agent ${this.name}`);
-    }
-    
-    // Build context
-    const context: AgentContext = {
-      agent: this,
-      network: options.context?.network,
-      state: options.context?.state,
-      telemetry: options.context?.telemetry || new Telemetry()
-    };
-    
-    // Prepare tools for the model
-    const availableTools = this.getAllTools();
-    
-    // Add system message if specified
-    const messages = [...options.messages];
-    if (this.system) {
-      messages.unshift({
-        role: 'system',
-        content: this.system
-      });
-    }
-    
-    // Execute with telemetry
-    return context.telemetry.trace(
-      `agent.${this.name}`,
-      async (span) => {
-        // Add agent metadata to span
-        span.setAttributes({
-          'agent.name': this.name,
-          'agent.id': this.id,
-          'agent.model': model.name || 'unknown',
-          'agent.tools.count': this.getAllTools().size,
-          'agent.mcp.servers': this.mcpServers.length,
-          'agent.messages.count': messages.length
-        });
-        
-        const startTime = Date.now();
-        
-        try {
-          let result;
-          if (options.stream) {
-            result = await this.runStream({ ...options, messages, model, context });
-          } else {
-            result = await this.runComplete({ ...options, messages, model, context });
-          }
-          
-          const duration = Date.now() - startTime;
-          
-          // Record metrics
-          if (context.telemetry && 'recordAgentExecution' in context.telemetry) {
-            (context.telemetry as any).recordAgentExecution(
-              this.name,
-              duration,
-              true,
-              {
-                model: model.name,
-                messageCount: messages.length,
-                toolsUsed: result.toolCalls?.length || 0
-              }
-            );
-          }
-          
-          return result;
-        } catch (error) {
-          const duration = Date.now() - startTime;
-          
-          // Record failed execution
-          if (context.telemetry && 'recordAgentExecution' in context.telemetry) {
-            (context.telemetry as any).recordAgentExecution(
-              this.name,
-              duration,
-              false,
-              {
-                model: model.name,
-                error: error instanceof Error ? error.message : String(error)
-              }
-            );
-          }
-          
-          throw error;
-        }
-      },
-      {
-        kind: SpanKind.CLIENT,
-        attributes: {
-          'agent.type': 'llm'
-        }
-      }
-    );
-  }
-  
-  private async runComplete(options: any): Promise<any> {
-    const { messages, model, context } = options;
-    
-    const response = await model.complete({
-      messages,
-      tools: Array.from(this.getAllTools().values()),
-      temperature: this.temperature,
-      maxTokens: this.maxTokens
-    });
-    
-    // Handle tool calls
-    if (response.toolCalls && response.toolCalls.length > 0) {
-      const toolResults = await this.executeToolCalls(response.toolCalls, context);
-      
-      // Add tool results to messages
-      messages.push({
-        role: 'assistant',
-        content: response.content,
-        toolCalls: response.toolCalls
-      });
-      
-      messages.push({
-        role: 'tool',
-        toolResults
-      });
-      
-      // Recursively call for the next response
-      return this.runComplete({ ...options, messages });
-    }
-    
-    return response;
-  }
-  
-  private async *runStream(options: any): AsyncIterableIterator<any> {
-    const { messages, model, context } = options;
-    
-    const stream = await model.stream({
-      messages,
-      tools: Array.from(this.getAllTools().values()),
-      temperature: this.temperature,
-      maxTokens: this.maxTokens
-    });
-    
-    // Handle streaming with tool calls
-    return this.handleStreamWithTools(stream, messages, context, options);
-  }
-  
-  private async *handleStreamWithTools(
-    stream: AsyncIterableIterator<any>,
-    messages: any[],
-    context: AgentContext,
-    options: any
-  ): AsyncIterableIterator<any> {
-    let content = '';
-    const toolCalls: any[] = [];
-    
-    for await (const chunk of stream) {
-      yield chunk;
-      
-      if (chunk.type === 'content') {
-        content += chunk.content;
-      } else if (chunk.type === 'tool_call') {
-        toolCalls.push(chunk.toolCall);
-      } else if (chunk.type === 'done' && toolCalls.length > 0) {
-        // Execute tool calls
-        const toolResults = await this.executeToolCalls(toolCalls, context);
-        
-        // Add to messages
-        messages.push({
-          role: 'assistant',
-          content,
-          toolCalls
-        });
-        
-        messages.push({
-          role: 'tool',
-          toolResults
-        });
-        
-        // Continue with next iteration
-        const nextStream = await this.runStream({ ...options, messages });
-        for await (const nextChunk of nextStream) {
-          yield nextChunk;
-        }
-      }
-    }
-  }
-  
-  private async executeToolCalls(toolCalls: any[], context: AgentContext): Promise<any[]> {
-    const results = [];
-    
-    for (const call of toolCalls) {
-      try {
-        const result = await this.executeTool(call.name, call.arguments, context);
-        results.push({
-          id: call.id,
-          result
-        });
-      } catch (error) {
-        results.push({
-          id: call.id,
-          error: String(error)
-        });
-      }
-    }
-    
-    return results;
-  }
-  
-  private async executeTool(name: string, args: any, context: AgentContext): Promise<any> {
-    const startTime = Date.now();
-    
-    try {
-      let result;
-      let toolType: 'local' | 'mcp' = 'local';
-      
-      // Check local tools first
-      if (this.tools.has(name)) {
-        const tool = this.tools.get(name)!;
-        result = await tool.handler(args, context);
-      } else {
-        // Check MCP tools
-        let found = false;
-        for (const [key, mcpTool] of this.mcpTools) {
-          const [serverName, toolName] = key.split(':');
-          if (toolName === name || key === name) {
-            toolType = 'mcp';
-            result = await mcpTool.client.callTool({
-              name: toolName,
-              arguments: args
-            });
-            found = true;
-            break;
-          }
-        }
-        
-        if (!found) {
-          throw new Error(`Tool '${name}' not found`);
-        }
-      }
-      
-      const duration = Date.now() - startTime;
-      
-      // Record tool usage metric
-      if (context.telemetry && 'recordToolUsage' in context.telemetry) {
-        (context.telemetry as any).recordToolUsage(
-          name,
-          this.name,
-          duration,
-          true
-        );
-      }
-      
-      // Add telemetry event
-      context.telemetry.recordEvent({
-        name: 'tool.executed',
-        attributes: {
-          'tool.name': name,
-          'tool.type': toolType,
-          'tool.duration': duration,
-          'agent.name': this.name
-        }
-      });
-      
-      return result;
-    } catch (error) {
-      const duration = Date.now() - startTime;
-      
-      // Record failed tool execution
-      if (context.telemetry && 'recordToolUsage' in context.telemetry) {
-        (context.telemetry as any).recordToolUsage(
-          name,
-          this.name,
-          duration,
-          false
-        );
-      }
-      
-      throw error;
-    }
-  }
-  
-  private getAllTools(): Map<string, any> {
-    const allTools = new Map();
-    
-    // Add local tools
-    for (const [name, tool] of this.tools) {
-      allTools.set(name, {
-        name: tool.name,
-        description: tool.description,
-        parameters: tool.parameters
-      });
-    }
-    
-    // Add MCP tools
-    for (const [key, mcpTool] of this.mcpTools) {
-      const [serverName, toolName] = key.split(':');
-      allTools.set(toolName, {
-        name: toolName,
-        description: mcpTool.tool.description,
-        parameters: mcpTool.tool.inputSchema
-      });
-    }
-    
-    return allTools;
-  }
-  
-  clone(overrides?: Partial<AgentConfig>): Agent {
-    return new Agent({
-      name: this.name,
-      description: this.description,
-      system: this.system,
-      tools: Array.from(this.tools.values()),
-      mcpServers: this.mcpServers,
-      model: this.model,
-      temperature: this.temperature,
-      maxTokens: this.maxTokens,
-      metadata: this.metadata,
-      ...overrides
-    });
-  }
-}
-
-export function createAgent(config: AgentConfig): Agent {
-  return new Agent(config);
-}
@@ -1 +0,0 @@
-export async function embed(params: any): Promise<any> { return { embeddings: [] }; }
@@ -1 +0,0 @@
-export async function generateObject(params: any): Promise<any> { return {}; }
@@ -1 +0,0 @@
-export async function* generateStream(params: any): AsyncIterableIterator<any> { yield { type: 'done' }; }
@@ -1 +0,0 @@
-export async function generateText(params: any): Promise<any> { return { text: '' }; }
@@ -1,418 +0,0 @@
-/**
- * Network implementation for agent collaboration
- */
-
-import { Agent } from './agent';
-import { State } from './state';
-import { Router } from './router';
-import { ModelInterface } from '../types';
-import { Telemetry, SpanKind } from '../telemetry';
-import { nanoid } from 'nanoid';
-import { EventEmitter } from 'events';
-
-export interface NetworkConfig {
-  name: string;
-  agents: Agent[];
-  defaultModel?: ModelInterface;
-  router?: Router | ((context: RouterContext) => Agent | undefined);
-  state?: State;
-  maxIterations?: number;
-  metadata?: Record<string, any>;
-}
-
-export interface RouterContext {
-  network: Network;
-  state: State;
-  messages: any[];
-  iteration: number;
-  history: ExecutionHistory[];
-}
-
-export interface ExecutionHistory {
-  agent: string;
-  input: any;
-  output: any;
-  timestamp: number;
-  duration: number;
-}
-
-export interface NetworkRunOptions {
-  messages: any[];
-  stream?: boolean;
-  onIteration?: (context: RouterContext) => void;
-  telemetry?: Telemetry;
-}
-
-export class Network extends EventEmitter {
-  readonly id: string;
-  readonly name: string;
-  readonly agents: Map<string, Agent>;
-  readonly defaultModel?: ModelInterface;
-  readonly router: Router;
-  readonly state: State;
-  readonly maxIterations: number;
-  readonly metadata: Record<string, any>;
-  
-  private initialized = false;
-  
-  constructor(config: NetworkConfig) {
-    super();
-    this.id = nanoid();
-    this.name = config.name;
-    this.agents = new Map();
-    this.defaultModel = config.defaultModel;
-    this.state = config.state || new State();
-    this.maxIterations = config.maxIterations || 10;
-    this.metadata = config.metadata || {};
-    
-    // Register agents
-    for (const agent of config.agents) {
-      this.agents.set(agent.name, agent);
-    }
-    
-    // Setup router
-    if (typeof config.router === 'function') {
-      this.router = new Router({ handler: config.router });
-    } else if (config.router) {
-      this.router = config.router;
-    } else {
-      // Default router - just use first agent
-      this.router = new Router({
-        handler: () => config.agents[0]
-      });
-    }
-  }
-  
-  async initialize(): Promise<void> {
-    if (this.initialized) return;
-    
-    // Initialize all agents
-    const initPromises = Array.from(this.agents.values()).map(agent => 
-      agent.initialize()
-    );
-    
-    await Promise.all(initPromises);
-    
-    this.initialized = true;
-    this.emit('initialized');
-  }
-  
-  async run(options: NetworkRunOptions): Promise<any> {
-    await this.initialize();
-    
-    const telemetry = options.telemetry || new Telemetry();
-    const history: ExecutionHistory[] = [];
-    let messages = [...options.messages];
-    
-    return telemetry.trace(
-      `network.${this.name}`,
-      async (span) => {
-        const networkStartTime = Date.now();
-        const agentExecutions = new Map<string, number>();
-        
-        // Add network metadata to span
-        span.setAttributes({
-          'network.name': this.name,
-          'network.id': this.id,
-          'network.agents.count': this.agents.size,
-          'network.maxIterations': this.maxIterations,
-          'network.messages.initial': messages.length
-        });
-        
-        try {
-          for (let iteration = 0; iteration < this.maxIterations; iteration++) {
-            // Build router context
-            const context: RouterContext = {
-              network: this,
-              state: this.state,
-              messages,
-              iteration,
-              history
-            };
-            
-            // Call iteration callback if provided
-            if (options.onIteration) {
-              options.onIteration(context);
-            }
-            
-            // Get next agent from router with telemetry
-            const nextAgent = await telemetry.trace(
-              `router.${this.name}`,
-              async () => this.router.route(context),
-              {
-                kind: SpanKind.INTERNAL,
-                attributes: { 'router.iteration': iteration }
-              }
-            );
-            
-            if (!nextAgent) {
-              // No more agents to run
-              this.emit('complete', { history, state: this.state });
-              telemetry.recordEvent({
-                name: 'network.complete',
-                attributes: {
-                  'network.name': this.name,
-                  'network.iterations': iteration,
-                  'network.reason': 'no_next_agent'
-                }
-              });
-              break;
-            }
-            
-            // Track agent executions
-            agentExecutions.set(
-              nextAgent.name,
-              (agentExecutions.get(nextAgent.name) || 0) + 1
-            );
-            
-            this.emit('agent:start', { agent: nextAgent.name, iteration });
-            
-            // Run agent
-            const startTime = Date.now();
-            
-            try {
-              const agentContext = {
-                network: this,
-                state: this.state,
-                telemetry
-              };
-              
-              const result = await nextAgent.run({
-                messages,
-                model: this.defaultModel,
-                context: agentContext,
-                stream: options.stream
-              });
-              
-              const duration = Date.now() - startTime;
-              
-              // Add to history
-              const historyEntry: ExecutionHistory = {
-                agent: nextAgent.name,
-                input: messages[messages.length - 1],
-                output: result,
-                timestamp: Date.now(),
-                duration
-              };
-              
-              history.push(historyEntry);
-              
-              // Update messages
-              if (result.content) {
-                messages.push({
-                  role: 'assistant',
-                  content: result.content,
-                  metadata: {
-                    agent: nextAgent.name
-                  }
-                });
-              }
-              
-              this.emit('agent:complete', { 
-                agent: nextAgent.name, 
-                iteration,
-                result,
-                duration 
-              });
-              
-              // Check for completion
-              if (this.state.kv.get('complete') === true) {
-                this.emit('complete', { history, state: this.state });
-                telemetry.recordEvent({
-                  name: 'network.complete',
-                  attributes: {
-                    'network.name': this.name,
-                    'network.iterations': iteration + 1,
-                    'network.reason': 'state_complete'
-                  }
-                });
-                break;
-              }
-              
-            } catch (error) {
-              this.emit('agent:error', { 
-                agent: nextAgent.name, 
-                iteration,
-                error 
-              });
-              throw error;
-            }
-          }
-          
-          const networkDuration = Date.now() - networkStartTime;
-          
-          // Record network execution metrics
-          if (telemetry && 'recordNetworkExecution' in telemetry) {
-            (telemetry as any).recordNetworkExecution(
-              this.name,
-              history.length,
-              networkDuration,
-              agentExecutions
-            );
-          }
-          
-          // Return final result
-          return {
-            messages,
-            history,
-            state: this.state.toJSON(),
-            iterations: history.length
-          };
-        } catch (error) {
-          const networkDuration = Date.now() - networkStartTime;
-          
-          // Record failed network execution
-          telemetry.recordEvent({
-            name: 'network.error',
-            attributes: {
-              'network.name': this.name,
-              'network.duration': networkDuration,
-              'network.iterations': history.length,
-              'error.message': error instanceof Error ? error.message : String(error)
-            }
-          });
-          
-          throw error;
-        }
-      },
-      {
-        kind: SpanKind.SERVER,
-        attributes: {
-          'network.type': 'agent_network'
-        }
-      }
-    );
-  }
-  
-  async *stream(options: NetworkRunOptions): AsyncIterableIterator<any> {
-    await this.initialize();
-    
-    const telemetry = options.telemetry || new Telemetry();
-    const history: ExecutionHistory[] = [];
-    let messages = [...options.messages];
-    
-    for (let iteration = 0; iteration < this.maxIterations; iteration++) {
-      // Build router context
-      const context: RouterContext = {
-        network: this,
-        state: this.state,
-        messages,
-        iteration,
-        history
-      };
-      
-      // Get next agent from router
-      const nextAgent = await this.router.route(context);
-      
-      if (!nextAgent) {
-        // No more agents to run
-        yield { type: 'complete', history, state: this.state.toJSON() };
-        break;
-      }
-      
-      yield { type: 'agent:start', agent: nextAgent.name, iteration };
-      
-      // Run agent
-      const startTime = Date.now();
-      const agentContext = {
-        network: this,
-        state: this.state,
-        telemetry
-      };
-      
-      // Stream from agent
-      const stream = await nextAgent.run({
-        messages,
-        model: this.defaultModel,
-        context: agentContext,
-        stream: true
-      });
-      
-      let content = '';
-      
-      for await (const chunk of stream) {
-        yield { ...chunk, agent: nextAgent.name };
-        
-        if (chunk.type === 'content') {
-          content += chunk.content;
-        }
-      }
-      
-      const duration = Date.now() - startTime;
-      
-      // Add to history
-      const historyEntry: ExecutionHistory = {
-        agent: nextAgent.name,
-        input: messages[messages.length - 1],
-        output: { content },
-        timestamp: Date.now(),
-        duration
-      };
-      
-      history.push(historyEntry);
-      
-      // Update messages
-      if (content) {
-        messages.push({
-          role: 'assistant',
-          content,
-          metadata: {
-            agent: nextAgent.name
-          }
-        });
-      }
-      
-      yield { 
-        type: 'agent:complete',
-        agent: nextAgent.name,
-        iteration,
-        duration
-      };
-      
-      // Check for completion
-      if (this.state.kv.get('complete') === true) {
-        yield { type: 'complete', history, state: this.state.toJSON() };
-        break;
-      }
-    }
-  }
-  
-  getAgent(name: string): Agent | undefined {
-    return this.agents.get(name);
-  }
-  
-  addAgent(agent: Agent): void {
-    this.agents.set(agent.name, agent);
-    this.emit('agent:added', { agent: agent.name });
-  }
-  
-  removeAgent(name: string): void {
-    if (this.agents.delete(name)) {
-      this.emit('agent:removed', { agent: name });
-    }
-  }
-  
-  reset(): void {
-    this.state.reset();
-    this.emit('reset');
-  }
-  
-  getMetrics(): {
-    totalIterations: number;
-    agentExecutions: Map<string, number>;
-    averageDuration: number;
-    errors: number;
-  } {
-    // This would be populated from telemetry in a real implementation
-    return {
-      totalIterations: 0,
-      agentExecutions: new Map(),
-      averageDuration: 0,
-      errors: 0
-    };
-  }
-}
-
-export function createNetwork(config: NetworkConfig): Network {
-  return new Network(config);
-}
@@ -1,38 +0,0 @@
-/**
- * Router implementation for agent networks
- */
-
-import { Agent } from './agent';
-import { Network } from './network';
-import { State } from './state';
-
-export interface RouterConfig {
-  handler: (context: RouterContext) => Agent | undefined | Promise<Agent | undefined>;
-  metadata?: Record<string, any>;
-}
-
-export interface RouterContext {
-  network: Network;
-  state: State;
-  messages: any[];
-  iteration: number;
-  history: any[];
-}
-
-export class Router {
-  private handler: RouterConfig['handler'];
-  readonly metadata: Record<string, any>;
-  
-  constructor(config: RouterConfig) {
-    this.handler = config.handler;
-    this.metadata = config.metadata || {};
-  }
-  
-  async route(context: RouterContext): Promise<Agent | undefined> {
-    return Promise.resolve(this.handler(context));
-  }
-}
-
-export function createRouter(config: RouterConfig): Router {
-  return new Router(config);
-}
@@ -1,257 +0,0 @@
-/**
- * State management for agent networks
- */
-
-import { EventEmitter } from 'events';
-import { z } from 'zod';
-
-export interface StateConfig {
-  schema?: z.ZodSchema;
-  initial?: Record<string, any>;
-  persistent?: boolean;
-}
-
-export interface StateChange {
-  key: string;
-  oldValue: any;
-  newValue: any;
-  timestamp: number;
-}
-
-export class State extends EventEmitter {
-  readonly kv: Map<string, any>;
-  readonly history: StateChange[];
-  readonly schema?: z.ZodSchema;
-  private readonly persistent: boolean;
-  
-  constructor(config: StateConfig = {}) {
-    super();
-    this.kv = new Map();
-    this.history = [];
-    this.schema = config.schema;
-    this.persistent = config.persistent || false;
-    
-    // Initialize with initial values
-    if (config.initial) {
-      for (const [key, value] of Object.entries(config.initial)) {
-        this.set(key, value);
-      }
-    }
-    
-    // Load from persistence if enabled
-    if (this.persistent) {
-      this.load();
-    }
-  }
-  
-  set(key: string, value: any): void {
-    // Validate against schema if provided
-    if (this.schema) {
-      const result = this.schema.safeParse({ ...this.toJSON(), [key]: value });
-      if (!result.success) {
-        throw new Error(`State validation failed: ${result.error.message}`);
-      }
-    }
-    
-    const oldValue = this.kv.get(key);
-    this.kv.set(key, value);
-    
-    // Record change
-    const change: StateChange = {
-      key,
-      oldValue,
-      newValue: value,
-      timestamp: Date.now()
-    };
-    
-    this.history.push(change);
-    
-    // Emit change event
-    this.emit('change', change);
-    this.emit(`change:${key}`, { oldValue, newValue: value });
-    
-    // Persist if enabled
-    if (this.persistent) {
-      this.save();
-    }
-  }
-  
-  get(key: string): any {
-    return this.kv.get(key);
-  }
-  
-  has(key: string): boolean {
-    return this.kv.has(key);
-  }
-  
-  delete(key: string): boolean {
-    const oldValue = this.kv.get(key);
-    const deleted = this.kv.delete(key);
-    
-    if (deleted) {
-      const change: StateChange = {
-        key,
-        oldValue,
-        newValue: undefined,
-        timestamp: Date.now()
-      };
-      
-      this.history.push(change);
-      this.emit('change', change);
-      this.emit(`change:${key}`, { oldValue, newValue: undefined });
-      
-      if (this.persistent) {
-        this.save();
-      }
-    }
-    
-    return deleted;
-  }
-  
-  clear(): void {
-    const oldState = this.toJSON();
-    this.kv.clear();
-    
-    // Record all deletions
-    for (const key of Object.keys(oldState)) {
-      const change: StateChange = {
-        key,
-        oldValue: oldState[key],
-        newValue: undefined,
-        timestamp: Date.now()
-      };
-      this.history.push(change);
-    }
-    
-    this.emit('clear', { oldState });
-    
-    if (this.persistent) {
-      this.save();
-    }
-  }
-  
-  reset(): void {
-    this.clear();
-    this.history.length = 0;
-    this.emit('reset');
-  }
-  
-  toJSON(): Record<string, any> {
-    const obj: Record<string, any> = {};
-    for (const [key, value] of this.kv) {
-      obj[key] = value;
-    }
-    return obj;
-  }
-  
-  fromJSON(data: Record<string, any>): void {
-    this.clear();
-    for (const [key, value] of Object.entries(data)) {
-      this.set(key, value);
-    }
-  }
-  
-  getHistory(key?: string): StateChange[] {
-    if (key) {
-      return this.history.filter(change => change.key === key);
-    }
-    return [...this.history];
-  }
-  
-  rollback(steps: number = 1): void {
-    if (steps > this.history.length) {
-      throw new Error('Cannot rollback more steps than history length');
-    }
-    
-    // Get changes to rollback
-    const changesToRollback = this.history.slice(-steps);
-    
-    // Apply rollback
-    for (const change of changesToRollback.reverse()) {
-      if (change.oldValue === undefined) {
-        this.kv.delete(change.key);
-      } else {
-        this.kv.set(change.key, change.oldValue);
-      }
-    }
-    
-    // Remove rolled back changes from history
-    this.history.length = this.history.length - steps;
-    
-    this.emit('rollback', { steps, changes: changesToRollback });
-    
-    if (this.persistent) {
-      this.save();
-    }
-  }
-  
-  // Persistence methods
-  private save(): void {
-    // Only available in browser environments
-    if (typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
-      const data = {
-        state: this.toJSON(),
-        history: this.history
-      };
-      (globalThis as any).localStorage.setItem('hanzo-ai-state', JSON.stringify(data));
-    }
-  }
-  
-  private load(): void {
-    // Only available in browser environments
-    if (typeof globalThis !== 'undefined' && 'localStorage' in globalThis) {
-      const stored = (globalThis as any).localStorage.getItem('hanzo-ai-state');
-      if (stored) {
-        try {
-          const data = JSON.parse(stored);
-          this.fromJSON(data.state);
-          this.history.push(...(data.history || []));
-        } catch (error) {
-          console.error('Failed to load state from storage:', error);
-        }
-      }
-    }
-  }
-  
-  // Computed properties
-  compute<T>(key: string, fn: (state: Record<string, any>) => T): T {
-    const state = this.toJSON();
-    const result = fn(state);
-    
-    // Cache computed value
-    this.set(`_computed_${key}`, result);
-    
-    return result;
-  }
-  
-  watch(key: string, callback: (value: any) => void): () => void {
-    const handler = ({ newValue }: any) => callback(newValue);
-    this.on(`change:${key}`, handler);
-    
-    // Return unsubscribe function
-    return () => {
-      this.off(`change:${key}`, handler);
-    };
-  }
-  
-  // State machine helpers
-  transition(from: string, to: string, stateKey: string = 'state'): boolean {
-    const current = this.get(stateKey);
-    
-    if (current === from) {
-      this.set(stateKey, to);
-      this.emit('transition', { from, to, stateKey });
-      return true;
-    }
-    
-    return false;
-  }
-  
-  inState(state: string, stateKey: string = 'state'): boolean {
-    return this.get(stateKey) === state;
-  }
-}
-
-export function createState(config?: StateConfig): State {
-  return new State(config);
-}
@@ -1,235 +0,0 @@
-/**
- * Tool implementation for agents
- */
-
-import { z } from 'zod';
-import { AgentContext } from './agent';
-
-export interface ToolConfig<TParams = any, TResult = any> {
-  name: string;
-  description: string;
-  parameters: z.ZodSchema<TParams>;
-  handler: (params: TParams, context: AgentContext) => Promise<TResult> | TResult;
-  examples?: Array<{
-    input: TParams;
-    output: TResult;
-    description?: string;
-  }>;
-  metadata?: Record<string, any>;
-}
-
-export class Tool<TParams = any, TResult = any> {
-  readonly name: string;
-  readonly description: string;
-  readonly parameters: z.ZodSchema<TParams>;
-  readonly handler: (params: TParams, context: AgentContext) => Promise<TResult> | TResult;
-  readonly examples?: ToolConfig<TParams, TResult>['examples'];
-  readonly metadata: Record<string, any>;
-  
-  constructor(config: ToolConfig<TParams, TResult>) {
-    this.name = config.name;
-    this.description = config.description;
-    this.parameters = config.parameters;
-    this.handler = config.handler;
-    this.examples = config.examples;
-    this.metadata = config.metadata || {};
-  }
-  
-  async execute(params: any, context: AgentContext): Promise<TResult> {
-    // Validate parameters
-    const result = this.parameters.safeParse(params);
-    if (!result.success) {
-      throw new Error(`Invalid parameters for tool '${this.name}': ${result.error.message}`);
-    }
-    
-    // Execute handler
-    return Promise.resolve(this.handler(result.data, context));
-  }
-  
-  getSchema(): any {
-    return {
-      name: this.name,
-      description: this.description,
-      parameters: this.zodToJsonSchema(this.parameters)
-    };
-  }
-  
-  private zodToJsonSchema(schema: z.ZodSchema): any {
-    // This is a simplified version - in production you'd use a proper converter
-    if (schema instanceof z.ZodObject) {
-      const shape = schema.shape;
-      const properties: any = {};
-      const required: string[] = [];
-      
-      for (const [key, value] of Object.entries(shape)) {
-        properties[key] = this.zodToJsonSchema(value as z.ZodSchema);
-        
-        // Check if field is required
-        if (!(value as any).isOptional()) {
-          required.push(key);
-        }
-      }
-      
-      return {
-        type: 'object',
-        properties,
-        required: required.length > 0 ? required : undefined
-      };
-    } else if (schema instanceof z.ZodString) {
-      return { type: 'string' };
-    } else if (schema instanceof z.ZodNumber) {
-      return { type: 'number' };
-    } else if (schema instanceof z.ZodBoolean) {
-      return { type: 'boolean' };
-    } else if (schema instanceof z.ZodArray) {
-      return {
-        type: 'array',
-        items: this.zodToJsonSchema((schema as any)._def.type)
-      };
-    }
-    
-    // Fallback
-    return { type: 'any' };
-  }
-}
-
-export function createTool<TParams = any, TResult = any>(
-  config: ToolConfig<TParams, TResult>
-): Tool<TParams, TResult> {
-  return new Tool(config);
-}
-
-// Common tool patterns
-export const commonTools = {
-  done: (onDone?: (result: any, context: AgentContext) => void) => 
-    createTool({
-      name: 'done',
-      description: 'Call this tool when you are finished with the task.',
-      parameters: z.object({
-        answer: z.string().describe("Final answer or result"),
-        summary: z.string().optional().describe("Brief summary of what was accomplished")
-      }),
-      handler: async (params, context) => {
-        context.network?.state.set('complete', true);
-        context.network?.state.set('answer', params.answer);
-        if (params.summary) {
-          context.network?.state.set('summary', params.summary);
-        }
-        
-        if (onDone) {
-          onDone(params, context);
-        }
-        
-        return { success: true };
-      }
-    }),
-    
-  handoff: () =>
-    createTool({
-      name: 'handoff',
-      description: 'Hand off the conversation to another agent.',
-      parameters: z.object({
-        agent: z.string().describe("Name of the agent to hand off to"),
-        context: z.string().describe("Context to provide to the next agent"),
-        priority: z.boolean().optional().describe("Whether this is a priority handoff")
-      }),
-      handler: async (params, context) => {
-        if (!context.network) {
-          throw new Error('Handoff requires a network context');
-        }
-        
-        context.network.state.set('nextAgent', params.agent);
-        context.network.state.set('handoffContext', params.context);
-        
-        return {
-          success: true,
-          agent: params.agent
-        };
-      }
-    }),
-    
-  askUser: () =>
-    createTool({
-      name: 'ask_user',
-      description: 'Ask the user for additional information or clarification.',
-      parameters: z.object({
-        question: z.string().describe("The question to ask the user"),
-        context: z.string().optional().describe("Additional context for the question"),
-        options: z.array(z.string()).optional().describe("Multiple choice options if applicable")
-      }),
-      handler: async (params, context) => {
-        context.network?.state.set('waitingForUser', true);
-        context.network?.state.set('userQuestion', params);
-        
-        return {
-          success: true,
-          waiting: true
-        };
-      }
-    }),
-    
-  remember: () =>
-    createTool({
-      name: 'remember',
-      description: 'Store information in long-term memory.',
-      parameters: z.object({
-        key: z.string().describe("Memory key"),
-        value: z.any().describe("Value to remember"),
-        category: z.string().optional().describe("Category for organization"),
-        ttl: z.number().optional().describe("Time to live in seconds")
-      }),
-      handler: async (params, context) => {
-        const memory = context.network?.state.get('memory') || {};
-        memory[params.key] = {
-          value: params.value,
-          category: params.category,
-          timestamp: Date.now(),
-          ttl: params.ttl
-        };
-        
-        context.network?.state.set('memory', memory);
-        
-        return { success: true };
-      }
-    }),
-    
-  recall: () =>
-    createTool({
-      name: 'recall',
-      description: 'Retrieve information from long-term memory.',
-      parameters: z.object({
-        key: z.string().optional().describe("Specific memory key"),
-        category: z.string().optional().describe("Category to search"),
-        query: z.string().optional().describe("Search query")
-      }),
-      handler: async (params, context) => {
-        const memory = context.network?.state.get('memory') || {};
-        
-        if (params.key) {
-          return memory[params.key]?.value || null;
-        }
-        
-        // Search by category or query
-        const results: any[] = [];
-        for (const [key, item] of Object.entries(memory)) {
-          const memItem = item as any;
-          
-          // Check TTL
-          if (memItem.ttl && Date.now() - memItem.timestamp > memItem.ttl * 1000) {
-            continue;
-          }
-          
-          if (params.category && memItem.category === params.category) {
-            results.push({ key, ...memItem });
-          } else if (params.query) {
-            const searchStr = JSON.stringify(memItem.value).toLowerCase();
-            if (searchStr.includes(params.query.toLowerCase())) {
-              results.push({ key, ...memItem });
-            }
-          }
-        }
-        
-        return results;
-      }
-    })
-};
@@ -1,45 +0,0 @@
-/**
- * Error types for @hanzo/ai
- */
-
-export class HanzoAIError extends Error {
-  constructor(message: string, public code?: string) {
-    super(message);
-    this.name = 'HanzoAIError';
-  }
-}
-
-export class AgentError extends HanzoAIError {
-  constructor(message: string, public agentName: string) {
-    super(message, 'AGENT_ERROR');
-    this.name = 'AgentError';
-  }
-}
-
-export class NetworkError extends HanzoAIError {
-  constructor(message: string, public networkName: string) {
-    super(message, 'NETWORK_ERROR');
-    this.name = 'NetworkError';
-  }
-}
-
-export class ToolError extends HanzoAIError {
-  constructor(message: string, public toolName: string) {
-    super(message, 'TOOL_ERROR');
-    this.name = 'ToolError';
-  }
-}
-
-export class MCPError extends HanzoAIError {
-  constructor(message: string, public serverName?: string) {
-    super(message, 'MCP_ERROR');
-    this.name = 'MCPError';
-  }
-}
-
-export class ValidationError extends HanzoAIError {
-  constructor(message: string, public field?: string) {
-    super(message, 'VALIDATION_ERROR');
-    this.name = 'ValidationError';
-  }
-}
@@ -1,45 +0,0 @@
-/**
- * @hanzo/ai - The AI Toolkit for TypeScript
- * AgentKit with MCP support and multi-provider integration
- */
-
-// Core exports
-export { createAgent } from './core/agent';
-export { createNetwork } from './core/network';
-export { createTool } from './core/tool';
-export { createRouter } from './core/router';
-export { createState } from './core/state';
-
-// Provider exports
-export { anthropic } from './providers/anthropic';
-export { openai } from './providers/openai';
-export { google } from './providers/google';
-export { mistral } from './providers/mistral';
-export { bedrock } from './providers/bedrock';
-export { vertex } from './providers/vertex';
-export { cohere } from './providers/cohere';
-export { hanzo } from './providers/hanzo';
-
-// Core functionality
-export { generateText } from './core/generate/text';
-export { generateStream } from './core/generate/stream';
-export { generateObject } from './core/generate/object';
-export { embed } from './core/embed';
-
-// Types
-export * from './types';
-
-// Utilities
-export { createCompletionId } from './utils/id';
-export { parseStreamPart } from './utils/stream';
-export { validateSchema } from './utils/schema';
-
-// Errors
-export * from './errors';
-
-// MCP exports
-export * from './mcp';
-
-// Tracing
-export * from './telemetry';
-export { createHanzoCloudTelemetry, HanzoCloudTelemetry } from './telemetry/hanzo-cloud';
@@ -1,461 +0,0 @@
-/**
- * MCP Server wrapper for Agents and Networks
- * Allows any agent or network to be exposed as an MCP server
- */
-
-import { Server as MCPServer } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { Agent } from '../core/agent';
-import { Network } from '../core/network';
-import { Tool } from '../core/tool';
-import { z } from 'zod';
-
-export interface AgentServerConfig {
-  agent?: Agent;
-  network?: Network;
-  name?: string;
-  version?: string;
-  metadata?: Record<string, any>;
-}
-
-export class AgentMCPServer {
-  private server: MCPServer;
-  private agent?: Agent;
-  private network?: Network;
-  
-  constructor(config: AgentServerConfig) {
-    if (!config.agent && !config.network) {
-      throw new Error('Either agent or network must be provided');
-    }
-    
-    this.agent = config.agent;
-    this.network = config.network;
-    
-    const name = config.name || this.agent?.name || this.network?.name || 'hanzo-agent';
-    const version = config.version || '1.0.0';
-    
-    this.server = new MCPServer({
-      name,
-      version,
-      metadata: config.metadata
-    });
-    
-    this.setupTools();
-    this.setupResources();
-    this.setupPrompts();
-  }
-  
-  private setupTools(): void {
-    if (this.agent) {
-      this.setupAgentTools();
-    } else if (this.network) {
-      this.setupNetworkTools();
-    }
-  }
-  
-  private setupAgentTools(): void {
-    if (!this.agent) return;
-    
-    // Expose agent's run method as a tool
-    this.server.setRequestHandler('tools/list', async () => ({
-      tools: [
-        {
-          name: `${this.agent.name}_chat`,
-          description: `Chat with ${this.agent.name} agent`,
-          inputSchema: {
-            type: 'object',
-            properties: {
-              message: {
-                type: 'string',
-                description: 'Message to send to the agent'
-              },
-              context: {
-                type: 'object',
-                description: 'Optional context',
-                properties: {
-                  history: {
-                    type: 'array',
-                    items: { type: 'object' },
-                    description: 'Previous messages'
-                  }
-                }
-              }
-            },
-            required: ['message']
-          }
-        },
-        // Expose all agent tools
-        ...Array.from(this.agent.tools.values()).map(tool => ({
-          name: `${this.agent!.name}_${tool.name}`,
-          description: tool.description,
-          inputSchema: this.toolToJsonSchema(tool)
-        }))
-      ]
-    }));
-    
-    // Handle tool calls
-    this.server.setRequestHandler('tools/call', async (request) => {
-      const { name, arguments: args } = request.params as any;
-      
-      if (name === `${this.agent!.name}_chat`) {
-        const result = await this.agent!.run({
-          messages: [
-            { role: 'user', content: args.message }
-          ],
-          context: args.context
-        });
-        
-        return {
-          content: [
-            {
-              type: 'text',
-              text: result.content || JSON.stringify(result)
-            }
-          ]
-        };
-      }
-      
-      // Check if it's one of the agent's tools
-      const toolName = name.replace(`${this.agent!.name}_`, '');
-      const tool = this.agent!.tools.get(toolName);
-      
-      if (tool) {
-        const result = await tool.execute(args, {
-          agent: this.agent!,
-          telemetry: {} as any
-        });
-        
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(result)
-            }
-          ]
-        };
-      }
-      
-      throw new Error(`Tool '${name}' not found`);
-    });
-  }
-  
-  private setupNetworkTools(): void {
-    if (!this.network) return;
-    
-    this.server.setRequestHandler('tools/list', async () => ({
-      tools: [
-        {
-          name: `${this.network.name}_run`,
-          description: `Run a task through the ${this.network.name} network`,
-          inputSchema: {
-            type: 'object',
-            properties: {
-              message: {
-                type: 'string',
-                description: 'Task or message for the network'
-              },
-              stream: {
-                type: 'boolean',
-                description: 'Whether to stream responses'
-              }
-            },
-            required: ['message']
-          }
-        },
-        {
-          name: `${this.network.name}_state_get`,
-          description: `Get a value from the network's state`,
-          inputSchema: {
-            type: 'object',
-            properties: {
-              key: {
-                type: 'string',
-                description: 'State key to retrieve'
-              }
-            },
-            required: ['key']
-          }
-        },
-        {
-          name: `${this.network.name}_state_set`,
-          description: `Set a value in the network's state`,
-          inputSchema: {
-            type: 'object',
-            properties: {
-              key: {
-                type: 'string',
-                description: 'State key'
-              },
-              value: {
-                description: 'Value to set'
-              }
-            },
-            required: ['key', 'value']
-          }
-        },
-        // Expose individual agents as tools
-        ...Array.from(this.network.agents.values()).map(agent => ({
-          name: `${this.network!.name}_agent_${agent.name}`,
-          description: `Run task through ${agent.name} agent in the network`,
-          inputSchema: {
-            type: 'object',
-            properties: {
-              message: {
-                type: 'string',
-                description: 'Message for the agent'
-              }
-            },
-            required: ['message']
-          }
-        }))
-      ]
-    }));
-    
-    this.server.setRequestHandler('tools/call', async (request) => {
-      const { name, arguments: args } = request.params as any;
-      
-      if (name === `${this.network!.name}_run`) {
-        const result = await this.network!.run({
-          messages: [
-            { role: 'user', content: args.message }
-          ],
-          stream: args.stream
-        });
-        
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(result)
-            }
-          ]
-        };
-      }
-      
-      if (name === `${this.network!.name}_state_get`) {
-        const value = this.network!.state.get(args.key);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(value)
-            }
-          ]
-        };
-      }
-      
-      if (name === `${this.network!.name}_state_set`) {
-        this.network!.state.set(args.key, args.value);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'State updated'
-            }
-          ]
-        };
-      }
-      
-      // Check for agent-specific tools
-      const agentMatch = name.match(new RegExp(`^${this.network!.name}_agent_(.+)$`));
-      if (agentMatch) {
-        const agentName = agentMatch[1];
-        const agent = this.network!.getAgent(agentName);
-        
-        if (agent) {
-          const result = await agent.run({
-            messages: [
-              { role: 'user', content: args.message }
-            ]
-          });
-          
-          return {
-            content: [
-              {
-                type: 'text',
-                text: result.content || JSON.stringify(result)
-              }
-            ]
-          };
-        }
-      }
-      
-      throw new Error(`Tool '${name}' not found`);
-    });
-  }
-  
-  private setupResources(): void {
-    this.server.setRequestHandler('resources/list', async () => ({
-      resources: [
-        {
-          uri: `agent://${this.agent?.name || this.network?.name}/state`,
-          name: 'State',
-          description: 'Current state of the agent/network',
-          mimeType: 'application/json'
-        },
-        {
-          uri: `agent://${this.agent?.name || this.network?.name}/metrics`,
-          name: 'Metrics',
-          description: 'Performance metrics',
-          mimeType: 'application/json'
-        }
-      ]
-    }));
-    
-    this.server.setRequestHandler('resources/read', async (request) => {
-      const { uri } = request.params as any;
-      
-      if (uri.endsWith('/state')) {
-        const state = this.network?.state.toJSON() || {
-          agent: this.agent?.name,
-          metadata: this.agent?.metadata
-        };
-        
-        return {
-          contents: [
-            {
-              uri,
-              mimeType: 'application/json',
-              text: JSON.stringify(state, null, 2)
-            }
-          ]
-        };
-      }
-      
-      if (uri.endsWith('/metrics')) {
-        const metrics = this.network?.getMetrics() || {
-          agent: this.agent?.name,
-          calls: 0 // Would be tracked in real implementation
-        };
-        
-        return {
-          contents: [
-            {
-              uri,
-              mimeType: 'application/json',
-              text: JSON.stringify(metrics, null, 2)
-            }
-          ]
-        };
-      }
-      
-      throw new Error(`Resource '${uri}' not found`);
-    });
-  }
-  
-  private setupPrompts(): void {
-    const prompts = [];
-    
-    if (this.agent && this.agent.system) {
-      prompts.push({
-        name: `${this.agent.name}_system`,
-        description: `System prompt for ${this.agent.name}`,
-        arguments: []
-      });
-    }
-    
-    this.server.setRequestHandler('prompts/list', async () => ({
-      prompts
-    }));
-    
-    this.server.setRequestHandler('prompts/get', async (request) => {
-      const { name } = request.params as any;
-      
-      if (name === `${this.agent?.name}_system`) {
-        return {
-          description: `System prompt for ${this.agent.name}`,
-          messages: [
-            {
-              role: 'system',
-              content: {
-                type: 'text',
-                text: this.agent!.system!
-              }
-            }
-          ]
-        };
-      }
-      
-      throw new Error(`Prompt '${name}' not found`);
-    });
-  }
-  
-  private toolToJsonSchema(tool: Tool): any {
-    // Convert Zod schema to JSON Schema
-    // This is simplified - would use a proper converter in production
-    return {
-      type: 'object',
-      properties: {},
-      required: []
-    };
-  }
-  
-  async start(): Promise<void> {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-  }
-  
-  async startHttp(port: number = 3000): Promise<void> {
-    // HTTP transport implementation
-    const { createServer } = await import('http');
-    const server = createServer(async (req, res) => {
-      if (req.method === 'POST') {
-        let body = '';
-        req.on('data', chunk => body += chunk);
-        req.on('end', async () => {
-          try {
-            const request = JSON.parse(body);
-            const response = await this.handleHttpRequest(request);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(response));
-          } catch (error) {
-            res.writeHead(500, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: String(error) }));
-          }
-        });
-      }
-    });
-    
-    server.listen(port);
-    console.log(`Agent MCP server listening on http://localhost:${port}`);
-  }
-  
-  private async handleHttpRequest(request: any): Promise<any> {
-    // Route to appropriate handler based on request method
-    const [namespace, method] = request.method.split('/');
-    
-    if (namespace === 'tools') {
-      if (method === 'list') {
-        return this.server.handleRequest({ ...request, method: 'tools/list' });
-      } else if (method === 'call') {
-        return this.server.handleRequest({ ...request, method: 'tools/call' });
-      }
-    }
-    
-    throw new Error(`Unknown method: ${request.method}`);
-  }
-}
-
-// Helper to create and start an MCP server for an agent/network
-export function exposeAsMCP(
-  agentOrNetwork: Agent | Network,
-  options?: {
-    transport?: 'stdio' | 'http';
-    port?: number;
-    name?: string;
-  }
-): AgentMCPServer {
-  const server = new AgentMCPServer({
-    agent: agentOrNetwork instanceof Agent ? agentOrNetwork : undefined,
-    network: agentOrNetwork instanceof Network ? agentOrNetwork : undefined,
-    name: options?.name
-  });
-  
-  if (options?.transport === 'http') {
-    server.startHttp(options.port);
-  } else {
-    server.start();
-  }
-  
-  return server;
-}
@@ -1,57 +0,0 @@
-/**
- * MCP Client implementation
- */
-
-import { MCPTransport, MCPTool, MCPResource, MCPPrompt } from './types';
-
-export interface MCPClientConfig {
-  name: string;
-  transport: MCPTransport;
-}
-
-export class MCPClient {
-  private config: MCPClientConfig;
-  
-  constructor(config?: MCPClientConfig) {
-    this.config = config || { name: 'default', transport: { type: 'stdio' } };
-  }
-  
-  async connect(config: MCPClientConfig): Promise<void> {
-    this.config = config;
-    // Implementation would connect to MCP server
-  }
-  
-  async listTools(): Promise<MCPTool[]> {
-    // Implementation would fetch tools from server
-    return [];
-  }
-  
-  async listResources(): Promise<MCPResource[]> {
-    // Implementation would fetch resources from server
-    return [];
-  }
-  
-  async listPrompts(): Promise<MCPPrompt[]> {
-    // Implementation would fetch prompts from server
-    return [];
-  }
-  
-  async callTool(params: { name: string; arguments: any }): Promise<any> {
-    // Implementation would call tool on server
-    return {};
-  }
-  
-  async readResource(uri: string): Promise<any> {
-    // Implementation would read resource from server
-    return {};
-  }
-  
-  async getPrompt(name: string, args?: any): Promise<any> {
-    // Implementation would get prompt from server
-    return {};
-  }
-  
-  async disconnect(): Promise<void> {
-    // Implementation would disconnect from server
-  }
-}
@@ -1,7 +0,0 @@
-/**
- * MCP exports
- */
-
-export * from './types';
-export * from './client';
-export * from './agent-server';
@@ -1,36 +0,0 @@
-/**
- * MCP types for @hanzo/ai
- */
-
-export interface MCPServer {
-  name: string;
-  transport: MCPTransport;
-  metadata?: Record<string, any>;
-}
-
-export interface MCPTransport {
-  type: 'stdio' | 'http' | 'websocket';
-  command?: string;
-  args?: string[];
-  url?: string;
-  headers?: Record<string, string>;
-}
-
-export interface MCPTool {
-  name: string;
-  description: string;
-  inputSchema: any; // JSON Schema
-}
-
-export interface MCPResource {
-  uri: string;
-  name: string;
-  description?: string;
-  mimeType?: string;
-}
-
-export interface MCPPrompt {
-  name: string;
-  description: string;
-  arguments?: any[];
-}
@@ -1,20 +0,0 @@
-/**
- * Anthropic provider
- */
-
-import { ModelInterface } from '../types';
-
-export const anthropic = (config: { apiKey: string; model?: string }): ModelInterface => {
-  return {
-    name: config.model || 'claude-3-opus-20240229',
-    async complete(params) {
-      // Implementation would call Anthropic API
-      return { content: 'Claude response' };
-    },
-    async *stream(params) {
-      // Implementation would stream from Anthropic
-      yield { type: 'content', content: 'Claude' };
-      yield { type: 'done' };
-    }
-  };
-};
@@ -1 +0,0 @@
-export const bedrock = (config: any) => ({ name: 'bedrock', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1 +0,0 @@
-export const cohere = (config: any) => ({ name: 'cohere', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1 +0,0 @@
-export const google = (config: any) => ({ name: 'gemini', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1 +0,0 @@
-export const hanzo = (config: any) => ({ name: 'hanzo', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1 +0,0 @@
-export const mistral = (config: any) => ({ name: 'mistral', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1,20 +0,0 @@
-/**
- * OpenAI provider
- */
-
-import { ModelInterface } from '../types';
-
-export const openai = (config: { apiKey: string; model?: string }): ModelInterface => {
-  return {
-    name: config.model || 'gpt-4',
-    async complete(params) {
-      // Implementation would call OpenAI API
-      return { content: 'OpenAI response' };
-    },
-    async *stream(params) {
-      // Implementation would stream from OpenAI
-      yield { type: 'content', content: 'OpenAI' };
-      yield { type: 'done' };
-    }
-  };
-};
@@ -1 +0,0 @@
-export const vertex = (config: any) => ({ name: 'vertex', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });
@@ -1,18 +0,0 @@
-// Server exports for @hanzo/ai
-// This module provides server-side specific functionality
-
-export { Agent } from '../core/agent'
-export { Network } from '../core/network'
-export { Router, type RouterContext } from '../core/router'
-export { State } from '../core/state'
-export { AgentMCPServer } from '../mcp/agent-server'
-
-// Re-export providers for server use
-export * from '../providers/anthropic'
-export * from '../providers/openai'
-export * from '../providers/google'
-export * from '../providers/bedrock'
-export * from '../providers/vertex'
-export * from '../providers/cohere'
-export * from '../providers/mistral'
-export * from '../providers/hanzo'
@@ -1,319 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { HanzoCloudTelemetry } from '../hanzo-cloud';
-
-// Mock fetch
-global.fetch = vi.fn();
-
-describe('HanzoCloudTelemetry', () => {
-  let telemetry: HanzoCloudTelemetry;
-  const mockConfig = {
-    cloudUrl: 'https://test.hanzo.ai',
-    apiKey: 'test-api-key',
-    projectId: 'test-project',
-    environment: 'test',
-    serviceName: 'test-service'
-  };
-  
-  beforeEach(() => {
-    vi.clearAllMocks();
-    (global.fetch as any).mockResolvedValue({
-      ok: true,
-      status: 200,
-      json: async () => ({})
-    });
-    
-    telemetry = new HanzoCloudTelemetry(mockConfig);
-  });
-  
-  afterEach(async () => {
-    await telemetry.shutdown();
-  });
-  
-  describe('initialization', () => {
-    it('should initialize with config', () => {
-      expect(telemetry).toBeInstanceOf(HanzoCloudTelemetry);
-    });
-    
-    it('should log initialization', async () => {
-      // Just verify that telemetry initializes without errors
-      // The log output is visible in stdout which confirms it works
-      const newTelemetry = new HanzoCloudTelemetry(mockConfig);
-      expect(newTelemetry).toBeInstanceOf(HanzoCloudTelemetry);
-      
-      await newTelemetry.shutdown();
-    });
-  });
-  
-  describe('logging', () => {
-    it('should log with trace context', async () => {
-      await telemetry.trace('test-operation', async () => {
-        telemetry.log('info', 'Test message', { custom: 'data' });
-      });
-    });
-    
-    it('should support all log levels', () => {
-      telemetry.log('debug', 'Debug message');
-      telemetry.log('info', 'Info message');
-      telemetry.log('warn', 'Warning message');
-      telemetry.log('error', 'Error message');
-    });
-  });
-  
-  describe('agent metrics', () => {
-    it('should record agent execution', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      const histogramSpy = vi.spyOn(telemetry, 'histogram');
-      const logSpy = vi.spyOn(telemetry, 'log');
-      
-      telemetry.recordAgentExecution('test-agent', 1000, true, {
-        model: 'gpt-4',
-        tokens: 150
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('agent.executions', 1, {
-        agent: 'test-agent',
-        success: 'true'
-      });
-      
-      expect(histogramSpy).toHaveBeenCalledWith('agent.execution.duration', 1000, {
-        agent: 'test-agent'
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('agent.tokens.used', 150, {
-        agent: 'test-agent',
-        model: 'gpt-4'
-      });
-      
-      expect(logSpy).toHaveBeenCalledWith(
-        'info',
-        'Agent test-agent executed',
-        expect.objectContaining({
-          agent: 'test-agent',
-          duration: 1000,
-          success: true,
-          model: 'gpt-4',
-          tokens: 150
-        })
-      );
-    });
-    
-    it('should record failed agent execution', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      
-      telemetry.recordAgentExecution('test-agent', 500, false, {
-        error: 'Test error'
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('agent.executions', 1, {
-        agent: 'test-agent',
-        success: 'false'
-      });
-    });
-  });
-  
-  describe('network metrics', () => {
-    it('should record network execution', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      const histogramSpy = vi.spyOn(telemetry, 'histogram');
-      const logSpy = vi.spyOn(telemetry, 'log');
-      
-      const agentExecutions = new Map([
-        ['agent1', 3],
-        ['agent2', 2]
-      ]);
-      
-      telemetry.recordNetworkExecution('test-network', 5, 3000, agentExecutions);
-      
-      expect(incrementSpy).toHaveBeenCalledWith('network.executions', 1, {
-        network: 'test-network'
-      });
-      
-      expect(histogramSpy).toHaveBeenCalledWith('network.iterations', 5, {
-        network: 'test-network'
-      });
-      
-      expect(histogramSpy).toHaveBeenCalledWith('network.execution.duration', 3000, {
-        network: 'test-network'
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('network.agent.executions', 3, {
-        network: 'test-network',
-        agent: 'agent1'
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('network.agent.executions', 2, {
-        network: 'test-network',
-        agent: 'agent2'
-      });
-      
-      expect(logSpy).toHaveBeenCalledWith(
-        'info',
-        'Network test-network completed',
-        expect.objectContaining({
-          network: 'test-network',
-          iterations: 5,
-          duration: 3000,
-          agents: { agent1: 3, agent2: 2 }
-        })
-      );
-    });
-  });
-  
-  describe('tool metrics', () => {
-    it('should record tool usage', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      const histogramSpy = vi.spyOn(telemetry, 'histogram');
-      
-      telemetry.recordToolUsage('search', 'agent1', 100, true);
-      
-      expect(incrementSpy).toHaveBeenCalledWith('tool.executions', 1, {
-        tool: 'search',
-        agent: 'agent1',
-        success: 'true'
-      });
-      
-      expect(histogramSpy).toHaveBeenCalledWith('tool.execution.duration', 100, {
-        tool: 'search',
-        agent: 'agent1'
-      });
-    });
-  });
-  
-  describe('MCP metrics', () => {
-    it('should record MCP connection', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      const gaugeSpy = vi.spyOn(telemetry, 'gauge');
-      const logSpy = vi.spyOn(telemetry, 'log');
-      
-      telemetry.recordMCPConnection('file-system', true, {
-        transport: 'stdio'
-      });
-      
-      expect(incrementSpy).toHaveBeenCalledWith('mcp.connections', 1, {
-        server: 'file-system',
-        success: 'true'
-      });
-      
-      expect(gaugeSpy).toHaveBeenCalledWith('mcp.servers.active', 1, {
-        server: 'file-system'
-      });
-      
-      expect(logSpy).toHaveBeenCalledWith(
-        'info',
-        'MCP server file-system connection established',
-        expect.objectContaining({
-          server: 'file-system',
-          transport: 'stdio'
-        })
-      );
-    });
-    
-    it('should record failed MCP connection', () => {
-      const incrementSpy = vi.spyOn(telemetry, 'increment');
-      const gaugeSpy = vi.spyOn(telemetry, 'gauge');
-      
-      telemetry.recordMCPConnection('file-system', false);
-      
-      expect(incrementSpy).toHaveBeenCalledWith('mcp.connections', 1, {
-        server: 'file-system',
-        success: 'false'
-      });
-      
-      expect(gaugeSpy).not.toHaveBeenCalled();
-    });
-  });
-  
-  describe('sessions', () => {
-    it('should create sessions', () => {
-      const setAttributesSpy = vi.spyOn(telemetry, 'setAttributes');
-      
-      const sessionId = telemetry.createSession();
-      
-      expect(sessionId).toMatch(/^session_\d+_[a-z0-9]+$/);
-      expect(setAttributesSpy).toHaveBeenCalledWith({
-        'hanzo.session.id': sessionId
-      });
-    });
-    
-    it('should use provided session ID', () => {
-      const setAttributesSpy = vi.spyOn(telemetry, 'setAttributes');
-      
-      const sessionId = telemetry.createSession('custom-session-123');
-      
-      expect(sessionId).toBe('custom-session-123');
-      expect(setAttributesSpy).toHaveBeenCalledWith({
-        'hanzo.session.id': 'custom-session-123'
-      });
-    });
-  });
-  
-  describe('metrics flushing', () => {
-    beforeEach(() => {
-      vi.useFakeTimers();
-    });
-    
-    afterEach(() => {
-      vi.useRealTimers();
-    });
-    
-    it('should buffer and flush metrics', async () => {
-      // Record some metrics
-      telemetry.increment('test.counter', 1);
-      telemetry.increment('test.counter', 2);
-      telemetry.gauge('test.gauge', 10);
-      telemetry.gauge('test.gauge', 20);
-      telemetry.histogram('test.histogram', 100);
-      telemetry.histogram('test.histogram', 200);
-      
-      // Manually trigger flush
-      await (telemetry as any).flushMetrics(mockConfig);
-      
-      expect(global.fetch).toHaveBeenCalledWith(
-        'https://test.hanzo.ai/v1/metrics',
-        expect.objectContaining({
-          method: 'POST',
-          headers: expect.objectContaining({
-            'Content-Type': 'application/json',
-            'x-api-key': 'test-api-key',
-            'x-project-id': 'test-project'
-          }),
-          body: expect.stringContaining('metrics')
-        })
-      );
-    });
-  });
-  
-  describe('error handling', () => {
-    it('should handle metrics send failure', async () => {
-      (global.fetch as any).mockResolvedValueOnce({
-        ok: false,
-        status: 500,
-        statusText: 'Internal Server Error'
-      });
-      
-      // Add some metrics to flush
-      telemetry.increment('test.counter', 1);
-      
-      // Trigger metrics flush - should not throw
-      await expect(
-        (telemetry as any).flushMetrics(mockConfig)
-      ).resolves.not.toThrow();
-      
-      // The error log is visible in stdout which confirms error handling works
-    });
-    
-    it('should handle network errors', async () => {
-      (global.fetch as any).mockRejectedValueOnce(new Error('Network error'));
-      
-      // Add some metrics to flush
-      telemetry.increment('test.counter', 1);
-      
-      // Trigger metrics flush - should not throw
-      await expect(
-        (telemetry as any).flushMetrics(mockConfig)
-      ).resolves.not.toThrow();
-      
-      // The error log is visible in stdout which confirms error handling works
-    });
-  });
-});
@@ -1,225 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { Telemetry } from '../index';
-import { SpanKind, SpanStatusCode } from '@opentelemetry/api';
-
-describe('Telemetry', () => {
-  let telemetry: Telemetry;
-  
-  beforeEach(() => {
-    telemetry = new Telemetry({
-      serviceName: 'test-service',
-      enabled: true
-    });
-  });
-  
-  afterEach(async () => {
-    await telemetry.shutdown();
-  });
-  
-  describe('span operations', () => {
-    it('should create and end spans', () => {
-      const span = telemetry.startSpan('test-span', {
-        kind: SpanKind.INTERNAL,
-        attributes: { 'test.attr': 'value' }
-      });
-      
-      expect(span).toBeDefined();
-      expect(span.end).toBeInstanceOf(Function);
-      
-      telemetry.endSpan('test-span', { code: SpanStatusCode.OK });
-    });
-    
-    it('should trace async operations', async () => {
-      const result = await telemetry.trace(
-        'async-operation',
-        async (span) => {
-          span.setAttribute('operation.type', 'test');
-          return 'success';
-        }
-      );
-      
-      expect(result).toBe('success');
-    });
-    
-    it('should trace sync operations', () => {
-      const result = telemetry.traceSync(
-        'sync-operation',
-        (span) => {
-          span.setAttribute('operation.type', 'test');
-          return 42;
-        }
-      );
-      
-      expect(result).toBe(42);
-    });
-    
-    it('should handle errors in traced operations', async () => {
-      const error = new Error('Test error');
-      
-      await expect(
-        telemetry.trace('failing-operation', async () => {
-          throw error;
-        })
-      ).rejects.toThrow('Test error');
-    });
-  });
-  
-  describe('events and attributes', () => {
-    it('should record events', () => {
-      const span = telemetry.startSpan('test-span');
-      
-      telemetry.recordEvent({
-        name: 'test.event',
-        attributes: { 'event.type': 'test' },
-        timestamp: Date.now()
-      }, span);
-      
-      telemetry.endSpan('test-span');
-    });
-    
-    it('should set attributes', () => {
-      const span = telemetry.startSpan('test-span');
-      
-      telemetry.setAttributes({
-        'attr1': 'value1',
-        'attr2': 42,
-        'attr3': true
-      }, span);
-      
-      telemetry.endSpan('test-span');
-    });
-    
-    it('should record exceptions', () => {
-      const span = telemetry.startSpan('test-span');
-      const error = new Error('Test exception');
-      
-      telemetry.recordException(error, span);
-      
-      telemetry.endSpan('test-span');
-    });
-  });
-  
-  describe('metrics', () => {
-    it('should emit metric events', () => {
-      const metricHandler = vi.fn();
-      telemetry.on('metric', metricHandler);
-      
-      telemetry.increment('test.counter', 1, { tag: 'value' });
-      
-      expect(metricHandler).toHaveBeenCalledWith({
-        name: 'test.counter',
-        value: 1,
-        type: 'counter',
-        tags: expect.objectContaining({ tag: 'value' }),
-        timestamp: expect.any(Number)
-      });
-    });
-    
-    it('should record gauges', () => {
-      const metricHandler = vi.fn();
-      telemetry.on('metric', metricHandler);
-      
-      telemetry.gauge('test.gauge', 42);
-      
-      expect(metricHandler).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: 'test.gauge',
-          value: 42,
-          type: 'gauge'
-        })
-      );
-    });
-    
-    it('should record histograms', () => {
-      const metricHandler = vi.fn();
-      telemetry.on('metric', metricHandler);
-      
-      telemetry.histogram('test.histogram', 123);
-      
-      expect(metricHandler).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: 'test.histogram',
-          value: 123,
-          type: 'histogram'
-        })
-      );
-    });
-  });
-  
-  describe('context propagation', () => {
-    it('should get trace context', async () => {
-      await telemetry.trace('test-op', async () => {
-        const context = telemetry.getTraceContext();
-        
-        expect(context).toBeInstanceOf(Object);
-        // In test environment with noop tracer, context might be empty
-        // This is expected behavior
-      });
-    });
-    
-    it('should create child telemetry instances', () => {
-      const child = telemetry.createChild('child-service', {
-        'child.attr': 'value'
-      });
-      
-      expect(child).toBeInstanceOf(Telemetry);
-      expect(child).not.toBe(telemetry);
-    });
-  });
-  
-  describe('lifecycle', () => {
-    it('should flush pending data', async () => {
-      const flushHandler = vi.fn();
-      telemetry.on('flush', flushHandler);
-      
-      // Create some spans
-      telemetry.startSpan('span1');
-      telemetry.startSpan('span2');
-      
-      await telemetry.flush();
-      
-      expect(flushHandler).toHaveBeenCalled();
-    });
-    
-    it('should shutdown cleanly', async () => {
-      const span = telemetry.startSpan('test-span');
-      
-      await telemetry.shutdown();
-      
-      // Should not throw
-      telemetry.endSpan('test-span');
-    });
-  });
-  
-  describe('disabled telemetry', () => {
-    it('should not create real spans when disabled', () => {
-      const disabledTelemetry = new Telemetry({
-        serviceName: 'test',
-        enabled: false
-      });
-      
-      const span = disabledTelemetry.startSpan('test-span');
-      
-      // Should return a no-op span
-      expect(span).toBeDefined();
-      expect(span.end).toBeInstanceOf(Function);
-      
-      // Should not throw
-      span.end();
-    });
-    
-    it('should not emit metrics when disabled', () => {
-      const disabledTelemetry = new Telemetry({
-        serviceName: 'test',
-        enabled: false
-      });
-      
-      const metricHandler = vi.fn();
-      disabledTelemetry.on('metric', metricHandler);
-      
-      disabledTelemetry.increment('test.counter');
-      
-      expect(metricHandler).not.toHaveBeenCalled();
-    });
-  });
-});
@@ -1,363 +0,0 @@
-/**
- * Hanzo Cloud telemetry integration
- * Connects to Hanzo Cloud's observability platform for centralized monitoring
- */
-
-import { Telemetry, TelemetryConfig } from './index';
-import * as opentelemetry from '@opentelemetry/api';
-import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-import { registerInstrumentations } from '@opentelemetry/instrumentation';
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import winston from 'winston';
-
-export interface HanzoCloudConfig extends TelemetryConfig {
-  cloudUrl: string;
-  apiKey: string;
-  projectId: string;
-  environment?: string;
-  serviceName?: string;
-  serviceVersion?: string;
-  logLevel?: 'debug' | 'info' | 'warn' | 'error';
-}
-
-export class HanzoCloudTelemetry extends Telemetry {
-  private logger: winston.Logger;
-  private exporter?: OTLPTraceExporter;
-  private provider?: NodeTracerProvider;
-  private metricsBuffer: Map<string, any[]> = new Map();
-  private flushInterval?: NodeJS.Timeout;
-  
-  constructor(config: HanzoCloudConfig) {
-    super(config);
-    
-    // Setup Winston logger with Hanzo Cloud format
-    this.logger = this.createLogger(config);
-    
-    // Initialize OpenTelemetry
-    this.initializeOpenTelemetry(config);
-    
-    // Start metrics flush interval
-    this.startMetricsFlush(config);
-    
-    // Log initialization
-    this.logger.info('Hanzo Cloud telemetry initialized', {
-      projectId: config.projectId,
-      environment: config.environment || 'development',
-      serviceName: config.serviceName || 'hanzo-ai'
-    });
-  }
-  
-  private createLogger(config: HanzoCloudConfig): winston.Logger {
-    // Tracing format that adds trace context to logs
-    const tracingFormat = winston.format((info) => {
-      const span = opentelemetry.trace.getActiveSpan();
-      if (span) {
-        const { spanId, traceId } = span.spanContext();
-        info['trace_id'] = traceId;
-        info['span_id'] = spanId;
-        info['project_id'] = config.projectId;
-        info['service.name'] = config.serviceName || 'hanzo-ai';
-      }
-      return info;
-    });
-    
-    return winston.createLogger({
-      level: config.logLevel || 'info',
-      format: winston.format.combine(
-        winston.format.errors({ stack: true }),
-        winston.format.timestamp(),
-        tracingFormat(),
-        winston.format.json()
-      ),
-      defaultMeta: {
-        service: config.serviceName || 'hanzo-ai',
-        environment: config.environment || 'development',
-        projectId: config.projectId
-      },
-      transports: [
-        new winston.transports.Console(),
-        // Could add HTTP transport to send logs to Hanzo Cloud
-      ]
-    });
-  }
-  
-  private initializeOpenTelemetry(config: HanzoCloudConfig): void {
-    // Enable OpenTelemetry debugging in development
-    if (config.environment === 'development') {
-      diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
-    }
-    
-    // Create resource
-    const resource = resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: config.serviceName || 'hanzo-ai',
-      [ATTR_SERVICE_VERSION]: config.serviceVersion || '1.0.0',
-      // stable semconv dropped deployment.environment; keep the raw key
-      'deployment.environment': config.environment || 'development',
-      'hanzo.project.id': config.projectId,
-      'hanzo.cloud.region': process.env.HANZO_CLOUD_REGION || 'us-east-1'
-    });
-
-    // Create OTLP exporter
-    this.exporter = new OTLPTraceExporter({
-      url: `${config.cloudUrl}/v1/traces`,
-      headers: {
-        'x-api-key': config.apiKey,
-        'x-project-id': config.projectId
-      }
-    });
-
-    // Create provider with batch processor (SDK 2.x: processors are
-    // constructor-only; addSpanProcessor was removed)
-    this.provider = new NodeTracerProvider({
-      resource,
-      spanProcessors: [
-        new BatchSpanProcessor(this.exporter, {
-          maxQueueSize: 1000,
-          maxExportBatchSize: 512,
-          scheduledDelayMillis: 5000,
-          exportTimeoutMillis: 30000
-        })
-      ]
-    });
-    
-    // Register as global provider
-    this.provider.register();
-    
-    // Register instrumentations for automatic tracing
-    registerInstrumentations({
-      instrumentations: [
-        // Add instrumentations as needed
-      ]
-    });
-  }
-  
-  private startMetricsFlush(config: HanzoCloudConfig): void {
-    // Flush metrics every 30 seconds
-    this.flushInterval = setInterval(() => {
-      this.flushMetrics(config);
-    }, 30000);
-    
-    // Listen for metric events
-    this.on('metric', (metric) => {
-      const key = `${metric.name}:${metric.type}`;
-      if (!this.metricsBuffer.has(key)) {
-        this.metricsBuffer.set(key, []);
-      }
-      this.metricsBuffer.get(key)!.push(metric);
-    });
-  }
-  
-  private async flushMetrics(config: HanzoCloudConfig): Promise<void> {
-    if (this.metricsBuffer.size === 0) return;
-    
-    const metrics = Array.from(this.metricsBuffer.entries()).map(([key, values]) => {
-      const [name, type] = key.split(':');
-      
-      // Aggregate metrics
-      if (type === 'counter') {
-        const sum = values.reduce((acc, m) => acc + m.value, 0);
-        return { name, type, value: sum, tags: values[0].tags };
-      } else if (type === 'gauge') {
-        // Use latest value for gauges
-        return values[values.length - 1];
-      } else if (type === 'histogram') {
-        // Calculate percentiles for histograms
-        const sorted = values.map(m => m.value).sort((a, b) => a - b);
-        return {
-          name,
-          type,
-          value: {
-            count: sorted.length,
-            min: sorted[0],
-            max: sorted[sorted.length - 1],
-            p50: sorted[Math.floor(sorted.length * 0.5)],
-            p95: sorted[Math.floor(sorted.length * 0.95)],
-            p99: sorted[Math.floor(sorted.length * 0.99)]
-          },
-          tags: values[0].tags
-        };
-      }
-      return values[0];
-    });
-    
-    // Send to Hanzo Cloud
-    try {
-      const response = await fetch(`${config.cloudUrl}/v1/metrics`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-api-key': config.apiKey,
-          'x-project-id': config.projectId
-        },
-        body: JSON.stringify({
-          metrics,
-          timestamp: Date.now()
-        })
-      });
-      
-      if (!response.ok) {
-        this.logger.error('Failed to send metrics to Hanzo Cloud', {
-          status: response.status,
-          statusText: response.statusText
-        });
-      }
-      
-      // Clear buffer after successful send
-      this.metricsBuffer.clear();
-    } catch (error) {
-      this.logger.error('Error sending metrics to Hanzo Cloud', { error });
-    }
-  }
-  
-  /**
-   * Log a message with trace context
-   */
-  log(level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: any): void {
-    this.logger[level](message, meta);
-  }
-  
-  /**
-   * Record an agent execution
-   */
-  recordAgentExecution(agentName: string, duration: number, success: boolean, metadata?: any): void {
-    this.increment('agent.executions', 1, {
-      agent: agentName,
-      success: success ? 'true' : 'false'
-    });
-    
-    this.histogram('agent.execution.duration', duration, {
-      agent: agentName
-    });
-    
-    if (metadata?.tokens) {
-      this.increment('agent.tokens.used', metadata.tokens, {
-        agent: agentName,
-        model: metadata.model || 'unknown'
-      });
-    }
-    
-    this.log('info', `Agent ${agentName} executed`, {
-      agent: agentName,
-      duration,
-      success,
-      ...metadata
-    });
-  }
-  
-  /**
-   * Record a network execution
-   */
-  recordNetworkExecution(
-    networkName: string,
-    iterations: number,
-    duration: number,
-    agentExecutions: Map<string, number>
-  ): void {
-    this.increment('network.executions', 1, {
-      network: networkName
-    });
-    
-    this.histogram('network.iterations', iterations, {
-      network: networkName
-    });
-    
-    this.histogram('network.execution.duration', duration, {
-      network: networkName
-    });
-    
-    // Record per-agent metrics within the network
-    for (const [agent, count] of agentExecutions) {
-      this.increment('network.agent.executions', count, {
-        network: networkName,
-        agent
-      });
-    }
-    
-    this.log('info', `Network ${networkName} completed`, {
-      network: networkName,
-      iterations,
-      duration,
-      agents: Object.fromEntries(agentExecutions)
-    });
-  }
-  
-  /**
-   * Record tool usage
-   */
-  recordToolUsage(toolName: string, agentName: string, duration: number, success: boolean): void {
-    this.increment('tool.executions', 1, {
-      tool: toolName,
-      agent: agentName,
-      success: success ? 'true' : 'false'
-    });
-    
-    this.histogram('tool.execution.duration', duration, {
-      tool: toolName,
-      agent: agentName
-    });
-  }
-  
-  /**
-   * Record MCP server connection
-   */
-  recordMCPConnection(serverName: string, success: boolean, metadata?: any): void {
-    this.increment('mcp.connections', 1, {
-      server: serverName,
-      success: success ? 'true' : 'false'
-    });
-    
-    if (success) {
-      this.gauge('mcp.servers.active', 1, {
-        server: serverName
-      });
-    }
-    
-    this.log('info', `MCP server ${serverName} connection ${success ? 'established' : 'failed'}`, {
-      server: serverName,
-      ...metadata
-    });
-  }
-  
-  /**
-   * Create a session for tracking related executions
-   */
-  createSession(sessionId?: string): string {
-    const id = sessionId || `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-    this.setAttributes({ 'hanzo.session.id': id });
-    return id;
-  }
-  
-  /**
-   * Enhanced shutdown with cleanup
-   */
-  async shutdown(): Promise<void> {
-    // Clear intervals
-    if (this.flushInterval) {
-      clearInterval(this.flushInterval);
-    }
-    
-    // Flush remaining metrics
-    await this.flushMetrics(this.config as HanzoCloudConfig);
-    
-    // Shutdown OpenTelemetry
-    if (this.provider) {
-      await this.provider.shutdown();
-    }
-    
-    // Call parent shutdown
-    await super.shutdown();
-    
-    this.logger.info('Hanzo Cloud telemetry shut down');
-  }
-}
-
-/**
- * Create a Hanzo Cloud telemetry instance
- */
-export function createHanzoCloudTelemetry(config: HanzoCloudConfig): HanzoCloudTelemetry {
-  return new HanzoCloudTelemetry(config);
-}
@@ -1,352 +0,0 @@
-/**
- * Telemetry integration for Hanzo AI
- * Provides distributed tracing, logging, and metrics for agent executions
- */
-
-import * as opentelemetry from '@opentelemetry/api';
-import { Span, SpanStatusCode, SpanKind } from '@opentelemetry/api';
-import { EventEmitter } from 'events';
-
-export interface TelemetryConfig {
-  serviceName?: string;
-  enabled?: boolean;
-  cloudUrl?: string;
-  apiKey?: string;
-  projectId?: string;
-  sessionId?: string;
-  metadata?: Record<string, any>;
-}
-
-export interface SpanContext {
-  traceId: string;
-  spanId: string;
-  traceFlags?: number;
-}
-
-export interface TelemetryEvent {
-  name: string;
-  attributes?: Record<string, any>;
-  timestamp?: number;
-}
-
-export class Telemetry extends EventEmitter {
-  private tracer: opentelemetry.Tracer;
-  private enabled: boolean;
-  private config: TelemetryConfig;
-  private activeSpans: Map<string, Span> = new Map();
-  
-  constructor(config: TelemetryConfig = {}) {
-    super();
-    this.config = {
-      serviceName: 'hanzo-ai',
-      enabled: true,
-      ...config
-    };
-    
-    this.enabled = this.config.enabled ?? true;
-    this.tracer = opentelemetry.trace.getTracer(
-      this.config.serviceName || 'hanzo-ai',
-      '1.0.0'
-    );
-  }
-  
-  /**
-   * Start a new span for tracing
-   */
-  startSpan(
-    name: string,
-    options?: {
-      kind?: SpanKind;
-      attributes?: Record<string, any>;
-      parent?: Span | SpanContext;
-    }
-  ): Span {
-    if (!this.enabled) {
-      return opentelemetry.trace.getTracer('noop').startSpan('noop');
-    }
-    
-    const spanOptions: opentelemetry.SpanOptions = {
-      kind: options?.kind || SpanKind.INTERNAL,
-      attributes: {
-        'service.name': this.config.serviceName,
-        'hanzo.ai.version': '1.0.0',
-        ...this.config.metadata,
-        ...options?.attributes
-      }
-    };
-    
-    // Handle parent span
-    let context = opentelemetry.context.active();
-    if (options?.parent) {
-      if ('spanContext' in options.parent) {
-        // It's a Span
-        context = opentelemetry.trace.setSpan(context, options.parent);
-      } else {
-        // It's a SpanContext - need to create a parent span
-        const parentSpan = this.tracer.startSpan('parent', {
-          context: opentelemetry.trace.setSpanContext(
-            opentelemetry.ROOT_CONTEXT,
-            options.parent as SpanContext
-          )
-        });
-        context = opentelemetry.trace.setSpan(context, parentSpan);
-      }
-    }
-    
-    const span = this.tracer.startSpan(name, spanOptions, context);
-    this.activeSpans.set(name, span);
-    
-    // Add default attributes
-    if (this.config.projectId) {
-      span.setAttribute('hanzo.project.id', this.config.projectId);
-    }
-    if (this.config.sessionId) {
-      span.setAttribute('hanzo.session.id', this.config.sessionId);
-    }
-    
-    return span;
-  }
-  
-  /**
-   * End a span
-   */
-  endSpan(name: string, status?: { code: SpanStatusCode; message?: string }): void {
-    const span = this.activeSpans.get(name);
-    if (span) {
-      if (status) {
-        span.setStatus(status);
-      }
-      span.end();
-      this.activeSpans.delete(name);
-    }
-  }
-  
-  /**
-   * Trace an async operation
-   */
-  async trace<T>(
-    name: string,
-    fn: (span: Span) => Promise<T>,
-    options?: {
-      kind?: SpanKind;
-      attributes?: Record<string, any>;
-    }
-  ): Promise<T> {
-    const span = this.startSpan(name, options);
-    
-    try {
-      const result = await fn(span);
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      this.recordException(error as Error, span);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error instanceof Error ? error.message : String(error)
-      });
-      throw error;
-    } finally {
-      span.end();
-      this.activeSpans.delete(name);
-    }
-  }
-  
-  /**
-   * Trace a sync operation
-   */
-  traceSync<T>(
-    name: string,
-    fn: (span: Span) => T,
-    options?: {
-      kind?: SpanKind;
-      attributes?: Record<string, any>;
-    }
-  ): T {
-    const span = this.startSpan(name, options);
-    
-    try {
-      const result = fn(span);
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      this.recordException(error as Error, span);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error instanceof Error ? error.message : String(error)
-      });
-      throw error;
-    } finally {
-      span.end();
-      this.activeSpans.delete(name);
-    }
-  }
-  
-  /**
-   * Record an exception in the current or specified span
-   */
-  recordException(error: Error, span?: Span): void {
-    const activeSpan = span || this.getCurrentSpan();
-    if (!activeSpan) return;
-    
-    activeSpan.recordException({
-      name: error.name,
-      message: error.message,
-      stack: error.stack
-    });
-    
-    // Add error attributes for observability platforms
-    activeSpan.setAttributes({
-      'error.type': error.name,
-      'error.message': error.message,
-      'error.stack': error.stack
-    });
-  }
-  
-  /**
-   * Record an event in the current or specified span
-   */
-  recordEvent(event: TelemetryEvent, span?: Span): void {
-    const activeSpan = span || this.getCurrentSpan();
-    if (!activeSpan) return;
-    
-    activeSpan.addEvent(event.name, event.attributes, event.timestamp);
-  }
-  
-  /**
-   * Set attributes on the current or specified span
-   */
-  setAttributes(attributes: Record<string, any>, span?: Span): void {
-    const activeSpan = span || this.getCurrentSpan();
-    if (!activeSpan) return;
-    
-    activeSpan.setAttributes(attributes);
-  }
-  
-  /**
-   * Get the currently active span
-   */
-  getCurrentSpan(): Span | undefined {
-    return opentelemetry.trace.getActiveSpan();
-  }
-  
-  /**
-   * Get the current trace context for propagation
-   */
-  getTraceContext(): Record<string, string> {
-    const span = this.getCurrentSpan();
-    if (!span) return {};
-    
-    const carrier: Record<string, string> = {};
-    opentelemetry.propagation.inject(
-      opentelemetry.trace.setSpan(opentelemetry.context.active(), span),
-      carrier
-    );
-    
-    return carrier;
-  }
-  
-  /**
-   * Create a child telemetry instance with inherited context
-   */
-  createChild(name: string, attributes?: Record<string, any>): Telemetry {
-    return new Telemetry({
-      ...this.config,
-      metadata: {
-        ...this.config.metadata,
-        ...attributes,
-        parent: name
-      }
-    });
-  }
-  
-  /**
-   * Record metrics
-   */
-  recordMetric(
-    name: string,
-    value: number,
-    type: 'counter' | 'gauge' | 'histogram' = 'gauge',
-    tags?: Record<string, string | number>
-  ): void {
-    if (!this.enabled) return;
-    
-    // Emit metric event for collection
-    this.emit('metric', {
-      name,
-      value,
-      type,
-      tags: {
-        ...this.config.metadata,
-        ...tags
-      },
-      timestamp: Date.now()
-    });
-  }
-  
-  /**
-   * Increment a counter metric
-   */
-  increment(name: string, value: number = 1, tags?: Record<string, string | number>): void {
-    this.recordMetric(name, value, 'counter', tags);
-  }
-  
-  /**
-   * Record a gauge metric
-   */
-  gauge(name: string, value: number, tags?: Record<string, string | number>): void {
-    this.recordMetric(name, value, 'gauge', tags);
-  }
-  
-  /**
-   * Record a histogram metric
-   */
-  histogram(name: string, value: number, tags?: Record<string, string | number>): void {
-    this.recordMetric(name, value, 'histogram', tags);
-  }
-  
-  /**
-   * Flush all pending telemetry data
-   */
-  async flush(): Promise<void> {
-    // End all active spans
-    for (const [name, span] of this.activeSpans) {
-      span.setStatus({ code: SpanStatusCode.OK });
-      span.end();
-    }
-    this.activeSpans.clear();
-    
-    // Emit flush event for collectors
-    this.emit('flush');
-  }
-  
-  /**
-   * Shutdown telemetry
-   */
-  async shutdown(): Promise<void> {
-    await this.flush();
-    this.removeAllListeners();
-  }
-}
-
-// Global telemetry instance
-let globalTelemetry: Telemetry | undefined;
-
-/**
- * Get or create the global telemetry instance
- */
-export function getTelemetry(config?: TelemetryConfig): Telemetry {
-  if (!globalTelemetry) {
-    globalTelemetry = new Telemetry(config);
-  }
-  return globalTelemetry;
-}
-
-/**
- * Set the global telemetry instance
- */
-export function setTelemetry(telemetry: Telemetry): void {
-  globalTelemetry = telemetry;
-}
-
-// Export types
-export { Span, SpanStatusCode, SpanKind } from '@opentelemetry/api';
@@ -1,58 +0,0 @@
-/**
- * Core types for @hanzo/ai
- */
-
-export interface ModelInterface {
-  name?: string;
-  complete(params: CompletionParams): Promise<CompletionResponse>;
-  stream(params: CompletionParams): AsyncIterableIterator<StreamChunk>;
-}
-
-export interface CompletionParams {
-  messages: Message[];
-  tools?: Tool[];
-  temperature?: number;
-  maxTokens?: number;
-}
-
-export interface CompletionResponse {
-  content?: string;
-  toolCalls?: ToolCall[];
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-}
-
-export interface StreamChunk {
-  type: 'content' | 'tool_call' | 'done';
-  content?: string;
-  toolCall?: ToolCall;
-}
-
-export interface Message {
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  content?: string;
-  toolCalls?: ToolCall[];
-  toolResults?: ToolResult[];
-  metadata?: Record<string, any>;
-}
-
-export interface Tool {
-  name: string;
-  description: string;
-  parameters: any; // JSON Schema
-}
-
-export interface ToolCall {
-  id: string;
-  name: string;
-  arguments: any;
-}
-
-export interface ToolResult {
-  id: string;
-  result?: any;
-  error?: string;
-}
@@ -1,8 +0,0 @@
-import { nanoid } from 'nanoid';
-
-/**
- * Creates a unique completion ID
- */
-export function createCompletionId(): string {
-  return `cmpl-${nanoid()}`;
-}
@@ -1,16 +0,0 @@
-import { z, ZodSchema } from 'zod';
-
-/**
- * Validates data against a schema
- */
-export function validateSchema<T>(
-  schema: ZodSchema<T>,
-  data: unknown
-): { success: true; data: T } | { success: false; error: z.ZodError } {
-  const result = schema.safeParse(data);
-  if (result.success) {
-    return { success: true, data: result.data };
-  } else {
-    return { success: false, error: result.error };
-  }
-}
@@ -1,25 +0,0 @@
-import { createParser, ParsedEvent } from 'eventsource-parser';
-
-export interface StreamPart {
-  type: 'text' | 'function_call' | 'tool_calls' | 'data' | 'error' | 'done';
-  value: any;
-}
-
-/**
- * Parses a stream part from a server-sent event
- */
-export function parseStreamPart(data: string): StreamPart | null {
-  try {
-    const parsed = JSON.parse(data);
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Creates an event source parser
- */
-export function createEventSourceParser(onParse: (event: ParsedEvent) => void) {
-  return createParser(onParse);
-}
@@ -1,14 +0,0 @@
-import { defineConfig } from 'tsup'
-
-export default defineConfig({
-  entry: {
-    index: 'src/index.ts',
-    'server/index': 'src/server/index.ts',
-  },
-  format: ['cjs', 'esm'],
-  dts: false, // Temporarily disable type generation - needs fixing
-  splitting: false,
-  sourcemap: true,
-  clean: true,
-  external: ['react'],
-})
@@ -1,26 +0,0 @@
-import { defineConfig } from 'vitest/config';
-import path from 'path';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json', 'html'],
-      exclude: [
-        'node_modules/',
-        'dist/',
-        '**/*.d.ts',
-        '**/*.config.*',
-        '**/mockData.ts',
-        '**/__tests__/**'
-      ]
-    }
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src')
-    }
-  }
-});
@@ -16,5 +16,11 @@
    "typescript": "^5.8.3",
    "vitest": "^3.2.6"
  },
-  "license": "MIT"
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
 }
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Permanent local-dev install of the Hanzo browser extension on Linux — NO snap,
+# NO web store, NO signing service. Builds from source and installs into:
+#
+#   • Firefox ESR   (/opt/firefox-esr) via an enterprise policy that
+#     force-installs the unsigned XPI into EVERY profile (signatures disabled).
+#     Truly permanent + launch-independent: any launch of that Firefox has it.
+#
+#   • Brave         (Chromium-family; arm64 has no Google-Chrome build) via a
+#     --load-extension launcher (/usr/local/bin/hanzo-brave + a desktop entry).
+#     The extension loads from the live dist dir, so a rebuild + relaunch picks
+#     up new code — the correct dev loop (no re-pack per change).
+#
+# Why these two: on this box (aarch64) apt ships ONLY snap redirects for
+# firefox/chromium, and Google Chrome has no Linux arm64 build. Firefox ESR and
+# Brave are the reliable non-snap arm64 browsers. On x86_64 the same script
+# works; swap Brave for google-chrome if preferred.
+#
+# Re-run after any `node src/build.js` to redeploy. Idempotent.
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+EXT_ROOT="$(cd "$REPO_DIR/../.." && pwd)"          # ~/work/hanzo/extension
+DIST="$EXT_ROOT/dist"
+STABLE=/opt/hanzo-ext                              # stable install location
+FF=/opt/firefox-esr
+
+echo "==> building extension from source"
+( cd "$REPO_DIR" && node src/build.js )
+[ -d "$DIST/firefox" ] && [ -d "$DIST/chrome" ] || { echo "build did not produce dist/{firefox,chrome}"; exit 1; }
+
+echo "==> packaging Firefox XPI"
+XPI=/tmp/hanzo-ai.xpi
+( cd "$DIST/firefox" && rm -f "$XPI" && zip -qr -X "$XPI" . )
+GECKO_ID=$(python3 -c 'import json;m=json.load(open("'"$DIST"'/firefox/manifest.json"));print((m.get("browser_specific_settings") or m.get("applications") or {}).get("gecko",{}).get("id",""))')
+[ -n "$GECKO_ID" ] || { echo "firefox manifest has no gecko id"; exit 1; }
+
+echo "==> staging stable copies under $STABLE (needs sudo)"
+sudo mkdir -p "$STABLE"
+sudo cp "$XPI" "$STABLE/hanzo-ai.xpi"
+sudo rm -rf "$STABLE/chrome" && sudo cp -r "$DIST/chrome" "$STABLE/chrome"
+
+if [ -x "$FF/firefox" ]; then
+  echo "==> Firefox ESR enterprise policy (force-install + signatures off)"
+  sudo mkdir -p "$FF/distribution"
+  sudo tee "$FF/distribution/policies.json" >/dev/null <<JSON
+{
+  "policies": {
+    "ExtensionSettings": {
+      "$GECKO_ID": { "installation_mode": "force_installed", "install_url": "file://$STABLE/hanzo-ai.xpi" }
+    },
+    "Preferences": { "xpinstall.signatures.required": { "Value": false, "Status": "locked" } },
+    "DisableAppUpdate": true
+  }
+}
+JSON
+else
+  echo "!! Firefox ESR not at $FF — install it (Mozilla arm64 ESR tarball) then re-run"
+fi
+
+if command -v brave-browser >/dev/null 2>&1; then
+  echo "==> Brave --load-extension launcher + desktop entry"
+  sudo tee /usr/local/bin/hanzo-brave >/dev/null <<'SH'
+#!/bin/bash
+exec /usr/bin/brave-browser --load-extension=/opt/hanzo-ext/chrome "$@"
+SH
+  sudo chmod +x /usr/local/bin/hanzo-brave
+  sudo tee /usr/share/applications/brave-hanzo-dev.desktop >/dev/null <<'DESK'
+[Desktop Entry]
+Version=1.0
+Name=Brave (Hanzo Dev)
+Comment=Brave with the local Hanzo browser extension
+Exec=/usr/local/bin/hanzo-brave %U
+Terminal=false
+Type=Application
+Icon=brave-browser
+Categories=Network;WebBrowser;
+DESK
+else
+  echo "!! brave-browser not found — install it, then re-run"
+fi
+
+CHROME_ID=$(python3 - <<PY
+import json,base64,hashlib
+m=json.load(open("$DIST/chrome/manifest.json")); k=m.get("key")
+if k:
+    h=hashlib.sha256(base64.b64decode(k)).hexdigest()[:32]
+    print(''.join(chr(ord('a')+int(c,16)) for c in h))
+PY
+)
+echo
+echo "DONE."
+echo "  Firefox: launch  $FF/firefox   (extension $GECKO_ID force-installed, every profile)"
+echo "  Brave:   launch  hanzo-brave    (extension ${CHROME_ID:-<key-derived>} via --load-extension)"
+echo "  Rebuild loop: node src/build.js && ./install-linux.sh   (then relaunch the browser)"
@@ -1,6 +1,6 @@
 {
  "name": "@hanzo/browser-extension",
-  "version": "1.9.29",
+  "version": "1.9.35",
  "description": "Hanzo AI Browser Extension",
  "main": "dist/background.js",
  "scripts": {
@@ -12,6 +12,8 @@
    "check:bundle-budget": "node scripts/check-bundle-budgets.mjs"
  },
  "dependencies": {
+    "@hanzo/ai": "^0.2.3",
+    "@hanzo/usage": "^0.1.6",
    "@supabase/supabase-js": "^2.50.3",
    "axios": "^1.10.0",
    "chalk": "^4.1.2",
@@ -36,5 +38,14 @@
  "engines": {
    "node": ">=18.0.0"
  },
-  "license": "MIT"
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "images",
+    "manifest.json"
+  ]
 }
@@ -0,0 +1,553 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createAiClient, type SearchEvent, type SearchMode, type SearchSource } from '@hanzo/ai';
+import { fetchNews, type NewsItem } from './news.js';
+import { AUTO_MODEL, fetchModelCatalog, type ChatModel, type ModelGroup } from './model-catalog.js';
+import { renderMarkdown } from './markdown.js';
+
+/**
+ * Hanzo Answer Engine — the shared AI-answer surface (query → streamed answer +
+ * inline citations + sources + live news). Backend = api.hanzo.ai ONLY, reached
+ * through the @hanzo/ai `search`/`deepResearch` primitive (the one place the
+ * capability is defined). Rendered on the @hanzo/gui primitive surface; strict
+ * monochrome per the Hanzo brand.
+ */
+
+export interface AnswerEngineProps {
+  apiBase: string;
+  /** Resolves the current IAM bearer, or null when signed out. */
+  getToken: () => Promise<string | null>;
+  /** Kicks off IAM sign-in (opens the OAuth tab). */
+  signIn: () => void;
+  /** Optional initial query (from the omnibox / address bar `?q=`). */
+  initialQuery?: string;
+}
+
+const MODES: { id: SearchMode; label: string; hint: string }[] = [
+  { id: 'search', label: 'Search', hint: 'Fast grounded answer' },
+  { id: 'news', label: 'News', hint: 'Recency-biased' },
+  { id: 'research', label: 'Research', hint: 'Multi-source synthesis' },
+  { id: 'deep', label: 'Deep', hint: 'Plan + wide research' },
+];
+
+const SOURCE_CHIPS = ['web', 'news', 'academic', 'github', 'reddit', 'x'];
+
+// Hanzo tiers mirror @hanzo/plans (the SoT for pricing); shown in the picker's
+// upgrade banner. Full plan detail lives at console.hanzo.ai/pricing.
+const PLAN_TIERS = [
+  { name: 'Pro', price: '$20' },
+  { name: 'Max', price: '$100' },
+  { name: 'Ultra', price: '$200' },
+];
+
+function HanzoMark({ size = 28 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 67 67" width={size} height={size} xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <path d="M22.21 67V44.6369H0V67H22.21Z" fill="currentColor" />
+      <path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z" fill="currentColor" />
+      <path d="M22.21 0H0V22.3184H22.21V0Z" fill="currentColor" />
+      <path d="M66.7198 0H44.5098V22.3184H66.7198V0Z" fill="currentColor" />
+      <path d="M66.7198 67V44.6369H44.5098V67H66.7198Z" fill="currentColor" />
+    </svg>
+  );
+}
+
+function ModelPicker({
+  groups,
+  current,
+  onPick,
+}: {
+  groups: ModelGroup[];
+  current: ChatModel;
+  onPick: (m: ChatModel) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [filter, setFilter] = useState('');
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', onDoc);
+    return () => document.removeEventListener('mousedown', onDoc);
+  }, [open]);
+
+  const q = filter.trim().toLowerCase();
+  const shown = useMemo(
+    () =>
+      groups
+        .map((g) => ({
+          ...g,
+          models: g.models.filter(
+            (m) => !q || m.name.toLowerCase().includes(q) || m.id.toLowerCase().includes(q),
+          ),
+        }))
+        .filter((g) => g.models.length),
+    [groups, q],
+  );
+
+  return (
+    <div className="ae-picker" ref={ref}>
+      <button className="ae-picker-btn" onClick={() => setOpen((v) => !v)} title="Choose model">
+        <span className="ae-dot" />
+        {current.name}
+        <svg viewBox="0 0 16 16" width="12" height="12" aria-hidden="true">
+          <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="1.5" />
+        </svg>
+      </button>
+      {open && (
+        <div className="ae-picker-menu">
+          <input
+            className="ae-picker-filter"
+            placeholder="Search models…"
+            value={filter}
+            autoFocus
+            onChange={(e) => setFilter(e.target.value)}
+          />
+          <div className="ae-picker-list">
+            <button
+              className={'ae-model-row' + (current.id === AUTO_MODEL.id ? ' active' : '')}
+              onClick={() => {
+                onPick(AUTO_MODEL);
+                setOpen(false);
+              }}
+            >
+              <span className="ae-model-name">Auto</span>
+              <span className="ae-model-desc">Routes to the best model</span>
+            </button>
+            {shown.map((g) => (
+              <div key={g.family} className="ae-model-group">
+                <div className="ae-model-group-label">{g.label}</div>
+                {g.models.map((m) => (
+                  <button
+                    key={m.id}
+                    className={'ae-model-row' + (current.id === m.id ? ' active' : '')}
+                    onClick={() => {
+                      onPick(m);
+                      setOpen(false);
+                    }}
+                  >
+                    <span className="ae-model-name">
+                      {m.name}
+                      {m.tier && <span className="ae-badge">{m.tier}</span>}
+                    </span>
+                    {m.description && <span className="ae-model-desc">{m.description}</span>}
+                  </button>
+                ))}
+              </div>
+            ))}
+          </div>
+          <a className="ae-plan-banner" href="https://console.hanzo.ai/pricing" target="_blank" rel="noreferrer">
+            <span>Unlock every model</span>
+            <span className="ae-plan-tiers">
+              {PLAN_TIERS.map((t) => (
+                <span key={t.name} className="ae-plan-tier">
+                  {t.name} <b>{t.price}</b>
+                </span>
+              ))}
+            </span>
+          </a>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SourceCard({ s, index }: { s: SearchSource; index: number }) {
+  let host = '';
+  try {
+    host = new URL(s.url).hostname.replace(/^www\./, '');
+  } catch {
+    host = s.url;
+  }
+  return (
+    <a className="ae-source" href={s.url} target="_blank" rel="noreferrer" title={s.title}>
+      <span className="ae-source-head">
+        {s.favicon ? <img src={s.favicon} alt="" width="14" height="14" /> : <span className="ae-dot" />}
+        <span className="ae-source-host">{host}</span>
+        <span className="ae-source-idx">{index + 1}</span>
+      </span>
+      <span className="ae-source-title">{s.title}</span>
+    </a>
+  );
+}
+
+function InputCard({
+  value,
+  onChange,
+  onSubmit,
+  mode,
+  setMode,
+  sources,
+  toggleSource,
+  models,
+  model,
+  setModel,
+  busy,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  onSubmit: () => void;
+  mode: SearchMode;
+  setMode: (m: SearchMode) => void;
+  sources: Set<string>;
+  toggleSource: (s: string) => void;
+  models: ModelGroup[];
+  model: ChatModel;
+  setModel: (m: ChatModel) => void;
+  busy: boolean;
+}) {
+  const taRef = useRef<HTMLTextAreaElement>(null);
+  useEffect(() => {
+    const ta = taRef.current;
+    if (!ta) return;
+    ta.style.height = 'auto';
+    ta.style.height = Math.min(ta.scrollHeight, 200) + 'px';
+  }, [value]);
+
+  return (
+    <div className="ae-card">
+      <textarea
+        ref={taRef}
+        className="ae-input"
+        placeholder="Type @ for sources or / for modes"
+        value={value}
+        rows={1}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            onSubmit();
+          }
+        }}
+      />
+      <div className="ae-card-row">
+        <div className="ae-chips">
+          {SOURCE_CHIPS.map((s) => (
+            <button
+              key={s}
+              className={'ae-chip' + (sources.has(s) ? ' on' : '')}
+              onClick={() => toggleSource(s)}
+              title={`@${s}`}
+            >
+              @{s}
+            </button>
+          ))}
+        </div>
+        <div className="ae-card-right">
+          <div className="ae-modes">
+            {MODES.map((m) => (
+              <button
+                key={m.id}
+                className={'ae-mode' + (mode === m.id ? ' on' : '')}
+                onClick={() => setMode(m.id)}
+                title={m.hint}
+              >
+                {m.label}
+              </button>
+            ))}
+          </div>
+          <ModelPicker groups={models} current={model} onPick={setModel} />
+          <button className="ae-send" onClick={onSubmit} disabled={busy || !value.trim()} title="Search (Enter)">
+            {busy ? (
+              <span className="ae-spinner" />
+            ) : (
+              <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true">
+                <path d="M3 13V3l10 5-10 5z" fill="currentColor" />
+              </svg>
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function AnswerEngine({ apiBase, getToken, signIn, initialQuery }: AnswerEngineProps) {
+  const [collapsed, setCollapsed] = useState(false);
+  const [query, setQuery] = useState('');
+  const [submitted, setSubmitted] = useState('');
+  const [mode, setMode] = useState<SearchMode>('search');
+  const [sources, setSources] = useState<Set<string>>(new Set());
+  const [modelGroups, setModelGroups] = useState<ModelGroup[]>([]);
+  const [model, setModel] = useState<ChatModel>(AUTO_MODEL);
+  const [news, setNews] = useState<NewsItem[]>([]);
+
+  const [phase, setPhase] = useState<'idle' | 'running' | 'done'>('idle');
+  const [status, setStatus] = useState('');
+  const [answer, setAnswer] = useState('');
+  const [answerSources, setAnswerSources] = useState<SearchSource[]>([]);
+  const [followUps, setFollowUps] = useState<string[]>([]);
+  const [error, setError] = useState('');
+  const [needAuth, setNeedAuth] = useState(false);
+  const abortRef = useRef<AbortController | null>(null);
+
+  // Load real model catalog + live news (both public — work signed out).
+  // Default stays on Auto ("routes to the best model"); the picker changes it.
+  useEffect(() => {
+    fetchModelCatalog(apiBase)
+      .then(({ groups }) => setModelGroups(groups))
+      .catch(() => {});
+    fetchNews().then(setNews).catch(() => {});
+  }, [apiBase]);
+
+  const client = useMemo(
+    () =>
+      createAiClient({
+        baseUrl: apiBase,
+        getToken: async () => {
+          const t = await getToken();
+          if (!t) throw new Error('__NO_TOKEN__');
+          return t;
+        },
+      }),
+    [apiBase, getToken],
+  );
+
+  const run = useCallback(
+    async (q: string) => {
+      const question = q.trim();
+      if (!question) return;
+      abortRef.current?.abort();
+      const ctrl = new AbortController();
+      abortRef.current = ctrl;
+
+      setSubmitted(question);
+      setPhase('running');
+      setStatus('Searching the web');
+      setAnswer('');
+      setAnswerSources([]);
+      setFollowUps([]);
+      setError('');
+      setNeedAuth(false);
+
+      const opts = {
+        mode,
+        model: model.id,
+        sources: [...sources],
+        signal: ctrl.signal,
+      };
+      try {
+        for await (const ev of client.search(question, opts) as AsyncGenerator<SearchEvent>) {
+          switch (ev.type) {
+            case 'status':
+              setStatus(
+                ev.stage === 'planning'
+                  ? 'Planning research'
+                  : ev.stage === 'searching'
+                    ? 'Searching the web' + (ev.detail ? `: ${ev.detail}` : '')
+                    : ev.stage === 'reading'
+                      ? 'Reading sources'
+                      : 'Writing the answer',
+              );
+              break;
+            case 'sources':
+              setAnswerSources(ev.sources);
+              break;
+            case 'text':
+              setAnswer((a) => a + ev.delta);
+              break;
+            case 'follow_ups':
+              setFollowUps(ev.questions);
+              break;
+            case 'done':
+              setPhase('done');
+              break;
+            case 'error':
+              if (ev.error.includes('__NO_TOKEN__') || /401|invalid api key/i.test(ev.error)) {
+                setNeedAuth(true);
+              } else {
+                setError(ev.error);
+              }
+              setPhase('done');
+              break;
+          }
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes('__NO_TOKEN__') || /401|invalid api key/i.test(msg)) setNeedAuth(true);
+        else setError(msg);
+        setPhase('done');
+      }
+    },
+    [client, mode, model, sources],
+  );
+
+  // Fire the initial (address-bar) query once models are ready enough.
+  const didInit = useRef(false);
+  useEffect(() => {
+    if (didInit.current || !initialQuery) return;
+    didInit.current = true;
+    setQuery(initialQuery);
+    void run(initialQuery);
+  }, [initialQuery, run]);
+
+  const submit = useCallback(() => void run(query), [query, run]);
+  const toggleSource = useCallback((s: string) => {
+    setSources((prev) => {
+      const next = new Set(prev);
+      next.has(s) ? next.delete(s) : next.add(s);
+      return next;
+    });
+  }, []);
+
+  const newThread = useCallback(() => {
+    abortRef.current?.abort();
+    setPhase('idle');
+    setQuery('');
+    setSubmitted('');
+    setAnswer('');
+    setAnswerSources([]);
+    setFollowUps([]);
+    setError('');
+    setNeedAuth(false);
+  }, []);
+
+  return (
+    <div className={'ae-root' + (collapsed ? ' collapsed' : '')}>
+      <aside className="ae-sidebar">
+        <div className="ae-side-top">
+          <button className="ae-brand" onClick={newThread} title="Hanzo">
+            <HanzoMark size={22} />
+            {!collapsed && <span>Hanzo</span>}
+          </button>
+          <button className="ae-collapse" onClick={() => setCollapsed((v) => !v)} title="Toggle sidebar">
+            <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
+              <path d="M6 3v10M3 3h10v10H3z" fill="none" stroke="currentColor" strokeWidth="1.3" />
+            </svg>
+          </button>
+        </div>
+        <button className="ae-new" onClick={newThread}>
+          <svg viewBox="0 0 16 16" width="15" height="15" aria-hidden="true">
+            <path d="M8 3v10M3 8h10" fill="none" stroke="currentColor" strokeWidth="1.5" />
+          </svg>
+          {!collapsed && <span>New thread</span>}
+        </button>
+        <nav className="ae-nav">
+          <a href="https://hanzo.chat" target="_blank" rel="noreferrer">Threads</a>
+          <a href="https://docs.hanzo.ai" target="_blank" rel="noreferrer">Docs</a>
+          <a href="https://hanzo.ai" target="_blank" rel="noreferrer">About</a>
+        </nav>
+        <div className="ae-side-bottom">
+          <button className="ae-signin" onClick={signIn}>
+            {collapsed ? '↪' : 'Sign in — free to start'}
+          </button>
+        </div>
+      </aside>
+
+      <main className="ae-main">
+        {phase === 'idle' ? (
+          <div className="ae-hero">
+            <div className="ae-wordmark">
+              <HanzoMark size={44} />
+              <span>Hanzo</span>
+            </div>
+            <div className="ae-hero-card">
+              <InputCard
+                value={query}
+                onChange={setQuery}
+                onSubmit={submit}
+                mode={mode}
+                setMode={setMode}
+                sources={sources}
+                toggleSource={toggleSource}
+                models={modelGroups}
+                model={model}
+                setModel={setModel}
+                busy={false}
+              />
+            </div>
+            {news.length > 0 && (
+              <div className="ae-news">
+                <div className="ae-news-head">Top stories</div>
+                <div className="ae-news-grid">
+                  {news.slice(0, 6).map((n) => (
+                    <a key={n.url} className="ae-news-item" href={n.url} target="_blank" rel="noreferrer">
+                      <span className="ae-news-title">{n.title}</span>
+                      <span className="ae-news-meta">
+                        {n.source}
+                        {typeof n.points === 'number' ? ` · ${n.points} pts` : ''}
+                      </span>
+                    </a>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        ) : (
+          <div className="ae-answer-wrap">
+            <div className="ae-answer-scroll">
+              <h1 className="ae-question">{submitted}</h1>
+
+              {answerSources.length > 0 && (
+                <div className="ae-sources">
+                  {answerSources.map((s, i) => (
+                    <SourceCard key={s.url} s={s} index={i} />
+                  ))}
+                </div>
+              )}
+
+              {phase === 'running' && !answer && (
+                <div className="ae-status">
+                  <span className="ae-spinner" /> {status}…
+                </div>
+              )}
+
+              {needAuth ? (
+                <div className="ae-auth">
+                  <p>Sign in with Hanzo to get AI answers.</p>
+                  <button className="ae-signin big" onClick={signIn}>
+                    Sign in — free to start
+                  </button>
+                </div>
+              ) : error ? (
+                <div className="ae-error">{error}</div>
+              ) : (
+                <div
+                  className="ae-answer markdown"
+                  dangerouslySetInnerHTML={{ __html: renderMarkdown(answer) }}
+                />
+              )}
+
+              {followUps.length > 0 && (
+                <div className="ae-followups">
+                  <div className="ae-followups-head">Follow-up</div>
+                  {followUps.map((f) => (
+                    <button
+                      key={f}
+                      className="ae-followup"
+                      onClick={() => {
+                        setQuery(f);
+                        void run(f);
+                      }}
+                    >
+                      {f}
+                      <span className="ae-followup-arrow">→</span>
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+
+            <div className="ae-answer-composer">
+              <InputCard
+                value={query}
+                onChange={setQuery}
+                onSubmit={submit}
+                mode={mode}
+                setMode={setMode}
+                sources={sources}
+                toggleSource={toggleSource}
+                models={modelGroups}
+                model={model}
+                setModel={setModel}
+                busy={phase === 'running'}
+              />
+            </div>
+          </div>
+        )}
+      </main>
+    </div>
+  );
+}
@@ -0,0 +1,80 @@
+/**
+ * Minimal, XSS-safe Markdown → HTML for the streamed answer. Escapes first,
+ * then applies a small whitelist of inline/block transforms. Only http(s) links
+ * are emitted. No dependency — the answer only needs headings, bold/italic,
+ * code, inline `[text](url)` citations, and bullet/number lists.
+ */
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function inline(s: string): string {
+  let out = escapeHtml(s);
+  // Inline code first so its contents aren't further transformed.
+  out = out.replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`);
+  // [text](url) — only http(s) URLs; text keeps prior transforms applied after.
+  out = out.replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, (_m, text, url) => {
+    const safeUrl = url.replace(/"/g, '%22');
+    return `<a href="${safeUrl}" target="_blank" rel="noreferrer">${text}</a>`;
+  });
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/(^|[^*])\*([^*]+)\*/g, '$1<em>$2</em>');
+  return out;
+}
+
+export function renderMarkdown(md: string): string {
+  const lines = md.replace(/\r\n/g, '\n').split('\n');
+  const html: string[] = [];
+  let listType: 'ul' | 'ol' | null = null;
+
+  const closeList = () => {
+    if (listType) {
+      html.push(`</${listType}>`);
+      listType = null;
+    }
+  };
+
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (!line.trim()) {
+      closeList();
+      continue;
+    }
+    const heading = /^(#{1,4})\s+(.*)$/.exec(line);
+    if (heading) {
+      closeList();
+      const level = heading[1].length + 1; // h2..h5
+      html.push(`<h${level}>${inline(heading[2])}</h${level}>`);
+      continue;
+    }
+    const bullet = /^[-*]\s+(.*)$/.exec(line);
+    if (bullet) {
+      if (listType !== 'ul') {
+        closeList();
+        html.push('<ul>');
+        listType = 'ul';
+      }
+      html.push(`<li>${inline(bullet[1])}</li>`);
+      continue;
+    }
+    const numbered = /^\d+\.\s+(.*)$/.exec(line);
+    if (numbered) {
+      if (listType !== 'ol') {
+        closeList();
+        html.push('<ol>');
+        listType = 'ol';
+      }
+      html.push(`<li>${inline(numbered[1])}</li>`);
+      continue;
+    }
+    closeList();
+    html.push(`<p>${inline(line)}</p>`);
+  }
+  closeList();
+  return html.join('\n');
+}
@@ -0,0 +1,88 @@
+/**
+ * Hanzo model catalog for the answer-engine model picker. Reads the REAL
+ * catalog from `GET api.hanzo.ai/v1/models` (public, no auth) and keeps the
+ * text/chat families — never a hardcoded or fabricated list. Switching the
+ * picker actually changes the `model` passed to the @hanzo/ai search primitive.
+ */
+
+export interface ChatModel {
+  id: string;
+  name: string;
+  description: string;
+  tier: string;
+  family: string;
+  context: number | null;
+}
+
+export interface ModelGroup {
+  family: string;
+  label: string;
+  models: ChatModel[];
+}
+
+interface ModelRow {
+  id: string;
+  name?: string;
+  fullName?: string;
+  description?: string;
+  tier?: string;
+  context?: number | null;
+}
+interface FamilyRow {
+  id: string;
+  name?: string;
+  description?: string;
+  models?: string[];
+}
+interface ModelsResponse {
+  data?: ModelRow[];
+  families?: FamilyRow[];
+}
+
+/** Text/chat families to surface in the picker (embedding/image/audio excluded). */
+const CHAT_FAMILIES = ["enso", "zen5", "zen3"];
+
+/** The "let the gateway route" option — mirrors Scira's Auto. */
+export const AUTO_MODEL: ChatModel = {
+  id: "auto",
+  name: "Auto",
+  description: "Routes to the best model",
+  tier: "",
+  family: "auto",
+  context: null,
+};
+
+export async function fetchModelCatalog(
+  apiBase: string,
+  signal?: AbortSignal,
+): Promise<{ groups: ModelGroup[]; flat: ChatModel[] }> {
+  const res = await fetch(`${apiBase}/v1/models`, signal ? { signal } : {});
+  if (!res.ok) throw new Error(`models ${res.status}`);
+  const body = (await res.json()) as ModelsResponse;
+
+  const byId = new Map<string, ModelRow>();
+  for (const row of body.data ?? []) byId.set(row.id, row);
+
+  const groups: ModelGroup[] = [];
+  for (const fam of body.families ?? []) {
+    if (!CHAT_FAMILIES.includes(fam.id)) continue;
+    const models: ChatModel[] = [];
+    for (const id of fam.models ?? []) {
+      const row = byId.get(id);
+      models.push({
+        id,
+        name: row?.name || row?.fullName || id,
+        description: row?.description || "",
+        tier: row?.tier || "",
+        family: fam.id,
+        context: row?.context ?? null,
+      });
+    }
+    if (models.length) {
+      groups.push({ family: fam.id, label: fam.name || fam.id, models });
+    }
+  }
+
+  const flat = groups.flatMap((g) => g.models);
+  return { groups, flat };
+}
@@ -0,0 +1,83 @@
+/**
+ * Realtime news / world feed for the Hanzo answer engine.
+ *
+ * ONE provider interface, two implementations:
+ *   - `hanzo`  — the Hanzo cloud feed (api.hanzo.ai). This is the intended
+ *     source; the cloud endpoint does not exist yet (see the Scira→clients/ai
+ *     capability-port plan), so it is the clearly-marked SEAM. When cloud ships
+ *     a news endpoint, set DEFAULT_FEED = 'hanzo' and nothing else changes.
+ *   - `hackernews` — a real, keyless, CORS-open live feed (Hacker News via the
+ *     Algolia API). The working default today. NOT a fabricated feed.
+ */
+
+export interface NewsItem {
+  title: string;
+  url: string;
+  source: string;
+  points?: number;
+  comments?: number;
+  author?: string;
+}
+
+export interface FeedProvider {
+  id: string;
+  label: string;
+  fetch(signal?: AbortSignal): Promise<NewsItem[]>;
+}
+
+/** Real live feed — Hacker News front page (keyless, `access-control-allow-origin: *`). */
+const hackerNews: FeedProvider = {
+  id: "hackernews",
+  label: "Top stories",
+  async fetch(signal) {
+    const res = await fetch(
+      "https://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=12",
+      signal ? { signal } : {},
+    );
+    if (!res.ok) throw new Error(`news ${res.status}`);
+    const data = (await res.json()) as { hits?: Array<Record<string, unknown>> };
+    return (data.hits ?? [])
+      .map((h) => ({
+        title: String(h.title ?? ""),
+        url: String(h.url ?? ""),
+        source: "Hacker News",
+        points: typeof h.points === "number" ? h.points : undefined,
+        comments: typeof h.num_comments === "number" ? h.num_comments : undefined,
+        author: typeof h.author === "string" ? h.author : undefined,
+      }))
+      .filter((n) => n.title && n.url);
+  },
+};
+
+/**
+ * The Hanzo cloud feed SEAM. Wire to `GET api.hanzo.ai/v1/news` once the cloud
+ * capability port lands; until then it throws so callers fall back to the real
+ * feed above. Kept here so the swap is one line (DEFAULT_FEED = 'hanzo').
+ */
+export function hanzoFeed(apiBase: string, getToken: () => Promise<string | null>): FeedProvider {
+  return {
+    id: "hanzo",
+    label: "Hanzo News",
+    async fetch(signal) {
+      const token = await getToken();
+      const res = await fetch(`${apiBase}/v1/news`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        ...(signal ? { signal } : {}),
+      });
+      if (!res.ok) throw new Error(`hanzo news ${res.status}`);
+      const data = (await res.json()) as { items?: NewsItem[] };
+      return data.items ?? [];
+    },
+  };
+}
+
+/** Active feed. Flip to 'hanzo' when the cloud news endpoint ships. */
+export const DEFAULT_FEED = "hackernews";
+
+export async function fetchNews(signal?: AbortSignal): Promise<NewsItem[]> {
+  try {
+    return await hackerNews.fetch(signal);
+  } catch {
+    return [];
+  }
+}
@@ -27,6 +27,7 @@ import {
  type ZapManager,
 } from './shared/zap.js';
 import { connectNativeZap, type NativeZapState } from './shared/native-zap.js';
+import { fetchAllUsage } from './shared/usage.js';
 import { pickEvaluable, wrapEvaluable } from './shared/evaluable.js';
 import {
  getRagConfig,
@@ -109,7 +110,11 @@ class HanzoFirefoxExtension {

  constructor() {
    console.log('[Hanzo] Firefox extension initializing...');
-    this.connect();
+    // Legacy ws://:9223 CDP bridge is OPT-IN (globalThis.HANZO_LEGACY_CDP). The
+    // default (and only) transport is the ZAP native host — see
+    // discoverZapServers() at EOF — matching Chrome. Without a bridge server the
+    // WS just error-looped, so it no longer runs unless explicitly enabled.
+    if ((globalThis as { HANZO_LEGACY_CDP?: boolean }).HANZO_LEGACY_CDP) this.connect();
  }

  private connect(): void {
@@ -3000,6 +3005,17 @@ browser.runtime.onMessage.addListener((request: any, sender: any, sendResponse:
        sendResponse({ success: false, error: 'Tab filesystem requires CDP bridge.' });
        break;

+      // AI provider usage (Claude + Codex, via @hanzo/usage)
+      case 'usage.fetch': {
+        try {
+          const providers = await fetchAllUsage();
+          sendResponse({ success: true, providers });
+        } catch (e: any) {
+          sendResponse({ success: false, error: e.message });
+        }
+        break;
+      }
+
      default:
        sendResponse({ success: false, error: `Unknown action: ${request.action}` });
        break;
@@ -3072,4 +3088,32 @@ browser.tabs.onRemoved.addListener((tabId) => {
  }
 });

+// ── Omnibox → Hanzo answer engine ────────────────────────────────────────
+// Firefox's address bar can't be silently hijacked (a security boundary), and
+// `chrome_settings_overrides.search_provider` default-engine takeover is policy
+// gated. The WebExtension mechanism that DOES work without opt-in is the
+// omnibox keyword: type `hanzo <query>` in the address bar → the query loads
+// the Hanzo answer engine (AI answer + sources + news) with ?q=. Same surface
+// as the new-tab landing.
+try {
+  const omnibox = (browser as any).omnibox;
+  if (omnibox) {
+    omnibox.setDefaultSuggestion({
+      description: 'Search Hanzo AI — AI answers with sources and realtime news',
+    });
+    omnibox.onInputEntered.addListener((text: string, disposition: string) => {
+      const url = browser.runtime.getURL('newtab.html') + '?q=' + encodeURIComponent(text);
+      if (disposition === 'newForegroundTab') {
+        void browser.tabs.create({ url });
+      } else if (disposition === 'newBackgroundTab') {
+        void browser.tabs.create({ url, active: false });
+      } else {
+        void browser.tabs.update({ url });
+      }
+    });
+  }
+} catch (e) {
+  console.warn('[Hanzo] omnibox unavailable:', e);
+}
+
 console.log('[Hanzo] Firefox background script loaded');
@@ -38,6 +38,7 @@ import { BrowserControl } from './browser-control';
 import { WebGPUAI } from './webgpu-ai';
 import { getCDPBridge, CDPBridge } from './browser-dispatch';
 import * as auth from './auth';
+import { fetchAllUsage } from './shared/usage.js';
 import { listModels, chatCompletion, ChatMessage } from './chat-client';
 import { PageMonitor } from './page-monitor';
 import {
@@ -1787,6 +1788,19 @@ async function handleMessage(request: any, sender: chrome.runtime.MessageSender,
      break;
    }

+    // --- AI provider usage (Claude + Codex, via @hanzo/usage) ---
+    case 'usage.fetch': {
+      (async () => {
+        try {
+          const providers = await fetchAllUsage();
+          sendResponse({ success: true, providers });
+        } catch (e: any) {
+          sendResponse({ success: false, error: e.message });
+        }
+      })();
+      break;
+    }
+
  }
 }

@@ -5,8 +5,18 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');

+// ONE output root: the extension repo root's `dist/` (NOT packages/browser/dist),
+// so every build lands at a short, stable path — `<extension-root>/dist/chrome`
+// is the Load-unpacked / native-messaging target, regardless of where `node
+// src/build.js` (or `pnpm build`) is invoked from. Derived from __dirname
+// (packages/browser/src → ../../../) so it's cwd-independent. Per-browser bundles
+// sit directly under OUT; the shared staging bundles + npm files sit at OUT root.
+const OUT = path.resolve(__dirname, '..', '..', '..', 'dist');
+const out = (...p) => path.join(OUT, ...p);
+
 async function build() {
  console.log('Building browser extension...');
+  console.log('Output root:', OUT);

  // The extension does NOT depend on `@hanzo/ui`. Primitives are served by
  // a small local shim aliased as `@hanzo/gui` so call-sites read like the
@@ -16,17 +26,27 @@ async function build() {
  const hanzoGuiShim = path.join(__dirname, 'gui-primitives.tsx');
  console.log('Using @hanzo/gui local primitives shim:', hanzoGuiShim);

+  // The Usage panel runs the headless @hanzo/usage engine in the background
+  // context. It's a published npm dependency (^0.1.6) — esbuild resolves it
+  // from node_modules like any package, so the build works identically locally
+  // and on CI (no sibling-repo path assumption).
+
+  // The answer engine (new-tab landing) consumes the @hanzo/ai SDK's `search`
+  // primitive — the ONE place the search/deep-research capability is defined.
+  // It's a published npm dependency (^0.2.3), so esbuild resolves it from
+  // node_modules like any other package — works identically locally and on CI
+  // (no sibling-repo path assumption).
+
  // Ensure dist directories exist
-  fs.mkdirSync('dist/browser-extension', { recursive: true });
-  fs.mkdirSync('dist/browser-extension/chrome', { recursive: true });
-  fs.mkdirSync('dist/browser-extension/firefox', { recursive: true });
-  fs.mkdirSync('dist/browser-extension/safari', { recursive: true });
+  for (const d of ['', 'chrome', 'firefox', 'safari']) {
+    fs.mkdirSync(out(d), { recursive: true });
+  }

  // Build content script
  await esbuild.build({
    entryPoints: ['src/content-script.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/content-script.js',
+    outfile: out('content-script.js'),
    platform: 'browser',
    target: ['chrome90', 'firefox91', 'safari14'],
    sourcemap: 'inline'
@@ -36,29 +56,29 @@ async function build() {
  await esbuild.build({
    entryPoints: ['src/background.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/background.js',
+    outfile: out('background.js'),
    platform: 'browser',
    target: ['chrome90', 'safari14'],
    format: 'esm',
-    external: ['chrome', 'browser']
+    external: ['chrome', 'browser'],
  });

  // Build Firefox-specific background script (no ESM export, uses browser.* APIs)
  await esbuild.build({
    entryPoints: ['src/background-firefox.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/background-firefox.js',
+    outfile: out('background-firefox.js'),
    platform: 'browser',
    target: ['firefox91'],
    format: 'iife',  // Immediately-invoked function expression (no exports)
-    external: ['browser']
+    external: ['browser'],
  });

  // Build WebGPU AI module
  await esbuild.build({
    entryPoints: ['src/webgpu-ai.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/webgpu-ai.js',
+    outfile: out('webgpu-ai.js'),
    platform: 'browser',
    target: 'es2020',
    format: 'esm'
@@ -73,7 +93,7 @@ async function build() {
  await esbuild.build({
    entryPoints: [fs.existsSync('src/sidebar.ts') ? 'src/sidebar.ts' : 'src/sidebar.js'],
    bundle: true,
-    outfile: 'dist/browser-extension/sidebar.js',
+    outfile: out('sidebar.js'),
    platform: 'browser',
    target: ['chrome90', 'firefox91', 'safari14'],
    sourcemap: 'inline',
@@ -83,17 +103,30 @@ async function build() {
  await esbuild.build({
    entryPoints: [fs.existsSync('src/popup.ts') ? 'src/popup.ts' : 'src/popup.js'],
    bundle: true,
-    outfile: 'dist/browser-extension/popup.js',
+    outfile: out('popup.js'),
    platform: 'browser',
    target: ['chrome90', 'firefox91', 'safari14'],
    sourcemap: 'inline',
  });

+  // Answer engine (new-tab landing + omnibox/address-bar search target).
+  // React 18 surface consuming the @hanzo/ai `search` primitive; monochrome.
+  await esbuild.build({
+    entryPoints: ['src/newtab.ts'],
+    bundle: true,
+    outfile: out('newtab.js'),
+    platform: 'browser',
+    target: ['chrome90', 'firefox91', 'safari14'],
+    // New-tab page loads on every tab — ship it lean (minified, no inline map).
+    minify: true,
+    sourcemap: false,
+  });
+
  // Build browser control module
  await esbuild.build({
    entryPoints: ['src/browser-control.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/browser-control.js',
+    outfile: out('browser-control.js'),
    platform: 'browser',
    target: 'es2020',
    format: 'esm'
@@ -103,7 +136,7 @@ async function build() {
  await esbuild.build({
    entryPoints: ['src/cli.ts'],
    bundle: true,
-    outfile: 'dist/browser-extension/cli.js',
+    outfile: out('cli.js'),
    platform: 'node',
    target: 'node16',
    packages: 'external'
@@ -111,16 +144,9 @@ async function build() {

  // Make CLI executable
  if (process.platform !== 'win32') {
-    execSync('chmod +x dist/browser-extension/cli.js');
+    fs.chmodSync(out('cli.js'), 0o755);
  }

-  // Build TypeScript declarations
-  console.log('Building TypeScript declarations...');
-  // Check if we should run tsc in root or src, based on where tsconfig is.
-  // Assuming root tsconfig covers src, or src has one.
-  // There is a tsconfig in src.
-  // execSync('cd src && npx tsc --noEmit', { stdio: 'inherit' });
-
  // Copy manifests for different browsers. package.json is the SINGLE source of
  // truth for the version — stamp it into every manifest so the three can never
  // drift apart (the "must agree" rule, enforced by the build instead of by hand).
@@ -130,12 +156,12 @@ async function build() {
    m.version = pkgVersion;
    fs.writeFileSync(destPath, JSON.stringify(m, null, 2));
  };
-  writeManifest('src/manifest.json', 'dist/browser-extension/manifest.json');
-  writeManifest('src/manifest.json', 'dist/browser-extension/chrome/manifest.json');
-  writeManifest('src/manifest-firefox.json', 'dist/browser-extension/firefox/manifest.json');
+  writeManifest('src/manifest.json', out('manifest.json'));
+  writeManifest('src/manifest.json', out('chrome', 'manifest.json'));
+  writeManifest('src/manifest-firefox.json', out('firefox', 'manifest.json'));

  // Safari needs special handling — write Info.plist for Xcode project
-  fs.writeFileSync('dist/browser-extension/safari/Info.plist', `<?xml version="1.0" encoding="UTF-8"?>
+  fs.writeFileSync(out('safari', 'Info.plist'), `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
@@ -159,36 +185,28 @@ async function build() {

  // Copy common files to each browser directory
  ['chrome', 'firefox', 'safari'].forEach(browserName => {
-    const dir = `dist/browser-extension/${browserName}`;
+    const dir = out(browserName);

-    fs.copyFileSync(
-      'dist/browser-extension/content-script.js',
-      `${dir}/content-script.js`
-    );
+    fs.copyFileSync(out('content-script.js'), path.join(dir, 'content-script.js'));
    // Firefox uses IIFE background (no ESM service workers); Chrome/Safari use ESM
    if (browserName === 'firefox') {
-      fs.copyFileSync(
-        'dist/browser-extension/background-firefox.js',
-        `${dir}/background.js`
-      );
+      fs.copyFileSync(out('background-firefox.js'), path.join(dir, 'background.js'));
    } else {
-      fs.copyFileSync(
-        'dist/browser-extension/background.js',
-        `${dir}/background.js`
-      );
+      fs.copyFileSync(out('background.js'), path.join(dir, 'background.js'));
    }

-    // Copy popup + sidebar HTML/CSS
-    for (const f of ['popup.html', 'popup.css', 'sidebar.html', 'sidebar.css', 'callback.html', 'ai-worker.js']) {
+    // Copy popup + sidebar + answer-engine HTML/CSS
+    for (const f of ['popup.html', 'popup.css', 'sidebar.html', 'sidebar.css', 'newtab.html', 'newtab.css', 'callback.html', 'ai-worker.js']) {
      const src = path.join('src', f);
      if (fs.existsSync(src)) {
        fs.copyFileSync(src, path.join(dir, f));
      }
    }

-    // Copy compiled popup/sidebar scripts
-    fs.copyFileSync('dist/browser-extension/popup.js', path.join(dir, 'popup.js'));
-    fs.copyFileSync('dist/browser-extension/sidebar.js', path.join(dir, 'sidebar.js'));
+    // Copy compiled popup/sidebar/newtab scripts
+    fs.copyFileSync(out('popup.js'), path.join(dir, 'popup.js'));
+    fs.copyFileSync(out('sidebar.js'), path.join(dir, 'sidebar.js'));
+    fs.copyFileSync(out('newtab.js'), path.join(dir, 'newtab.js'));

    // Copy icons into each browser directory
    for (const icon of ['icon16.png', 'icon48.png', 'icon128.png']) {
@@ -202,13 +220,10 @@ async function build() {
  // Copy package.json for npm
  const pkg = JSON.parse(fs.readFileSync('src/package.json', 'utf8'));
  pkg.main = 'cli.js';
-  fs.writeFileSync(
-    'dist/browser-extension/package.json',
-    JSON.stringify(pkg, null, 2)
-  );
+  fs.writeFileSync(out('package.json'), JSON.stringify(pkg, null, 2));

  // Create README for npm package
-  fs.writeFileSync('dist/browser-extension/README.md', `# Hanzo Browser DevTools
+  fs.writeFileSync(out('README.md'), `# Hanzo Browser DevTools

 Click-to-code navigation for web developers with MCP integration.

@@ -257,32 +272,33 @@ server.on('elementSelected', (data) => {
  ['icon16.png', 'icon48.png', 'icon128.png'].forEach(icon => {
    const iconPath = path.join('images', icon);
    if (fs.existsSync(iconPath)) {
-      fs.copyFileSync(iconPath, path.join('dist/browser-extension', icon));
+      fs.copyFileSync(iconPath, out(icon));
    }
  });

-  // Generate Safari Xcode project (macOS + iOS) if safari-web-extension-converter exists
+  // Generate Safari Xcode project (macOS + iOS) if safari-web-extension-converter exists.
+  // Project goes to dist/safari-xcode/ so it never collides with the dist/safari/ web-ext dir.
  try {
    execSync('xcrun --find safari-web-extension-converter', { stdio: 'ignore' });
    console.log('Generating Safari Xcode project (macOS + iOS)...');
    execSync(
-      `xcrun safari-web-extension-converter dist/browser-extension/chrome/ ` +
-      `--project-location dist/safari ` +
+      `xcrun safari-web-extension-converter ${out('chrome')}/ ` +
+      `--project-location ${out('safari-xcode')} ` +
      `--app-name "Hanzo AI" ` +
      `--bundle-identifier ai.hanzo.browser-extension ` +
      `--no-prompt --no-open --force`,
      { stdio: 'inherit' }
    );
-    console.log('📦 Safari: dist/safari/ (macOS + iOS Xcode project)');
+    console.log(`📦 Safari: ${out('safari-xcode')} (macOS + iOS Xcode project)`);
  } catch {
    console.log('⚠️  Safari: skipped (Xcode not available)');
  }

  console.log('✅ Browser extension built successfully!');
-  console.log('📦 Chrome: dist/browser-extension/chrome/');
-  console.log('📦 Firefox: dist/browser-extension/firefox/');
-  console.log('📦 NPM package ready in: dist/browser-extension/');
-  console.log('\nTo publish to npm: cd dist/browser-extension && npm publish');
+  console.log(`📦 Chrome:  ${out('chrome')}/`);
+  console.log(`📦 Firefox: ${out('firefox')}/`);
+  console.log(`📦 NPM package ready in: ${OUT}/`);
+  console.log(`\nTo publish to npm: cd ${OUT} && npm publish`);
 }

 build().catch((error) => {
@@ -1,8 +1,8 @@
 {
  "manifest_version": 3,
  "name": "Hanzo AI",
-  "version": "1.9.22",
-  "description": "AI-powered dev assistant — click-to-code navigation, source maps, WebGPU AI, and MCP integration for Claude Code.",
+  "version": "1.9.34",
+  "description": "AI answer engine, search, and dev assistant — Hanzo AI in a new tab, address-bar search, source-cited answers, realtime news, WebGPU AI, and MCP.",
  "permissions": [
    "activeTab",
    "identity",
@@ -17,6 +17,8 @@
  "host_permissions": [
    "http://localhost/*",
    "https://localhost/*",
+    "https://claude.ai/*",
+    "https://chatgpt.com/*",
    "<all_urls>"
  ],
  "content_security_policy": {
@@ -47,6 +49,12 @@
      "128": "icon128.png"
    }
  },
+  "chrome_url_overrides": {
+    "newtab": "newtab.html"
+  },
+  "omnibox": {
+    "keyword": "hanzo"
+  },
  "sidebar_action": {
    "default_title": "Hanzo AI",
    "default_panel": "sidebar.html",
@@ -1,8 +1,8 @@
 {
  "manifest_version": 3,
  "name": "Hanzo AI",
-  "version": "1.9.25",
-  "description": "AI-powered dev assistant — click-to-code navigation, source maps, WebGPU AI, and MCP integration for Claude Code.",
+  "version": "1.9.34",
+  "description": "AI answer engine, search, and dev assistant — Hanzo AI in a new tab, address-bar search, source-cited answers, realtime news, WebGPU AI, and MCP.",
  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxfXGh0lPUT5m04GKfjUwrLsV6pLaK3VcZuFRPogqAir2tzyLYnQPRtHynue9yvDyguIVnlkwvcwfDOYZrvH76zbw4s6onPBG8HqTKO6LQ9K3kdO1qBBkMMjdOgULQ1MrWThEbpU7NSTiwLYpEta/jAvrKRCAeKIlQE8p6htZmPy9aRUZuae66JgLcAlzD2vviX9sVB1asFABJVswL1RgZ55/8IzZaUrFjzOo9OHK4hmEOtudzkML+5silsAYdC+1BZugph2x94ai17YmZTCL1XyUa5Ke4q80cj+i9rOTgzhZs+mruyhL/AvNVOXilsgqCdNqSz77naWzC3pVGbxOewIDAQAB",
  "permissions": [
    "activeTab",
@@ -19,6 +19,8 @@
  "host_permissions": [
    "http://localhost/*",
    "https://localhost/*",
+    "https://claude.ai/*",
+    "https://chatgpt.com/*",
    "<all_urls>"
  ],
  "content_security_policy": {
@@ -52,6 +54,19 @@
    "48": "icon48.png",
    "128": "icon128.png"
  },
+  "chrome_url_overrides": {
+    "newtab": "newtab.html"
+  },
+  "chrome_settings_overrides": {
+    "search_provider": {
+      "name": "Hanzo",
+      "keyword": "hanzo",
+      "search_url": "https://hanzo.chat/c/new?q={searchTerms}&submit=true",
+      "favicon_url": "https://hanzo.ai/favicon.ico",
+      "encoding": "UTF-8",
+      "is_default": true
+    }
+  },
  "web_accessible_resources": [
    {
      "resources": [
@@ -0,0 +1,277 @@
+/* Hanzo Answer Engine — strict monochrome (brand primaryColor #FFFFFF).
+   Shared tokens mirror popup.css / sidebar.css. */
+:root {
+  --bg: #0a0a0a;
+  --surface: #0f0f0f;
+  --surface-2: #171717;
+  --surface-3: #1e1e1e;
+  --text: #fafafa;
+  --text-2: #a3a3a3;
+  --text-3: #666666;
+  --border: rgba(255, 255, 255, 0.10);
+  --border-2: rgba(255, 255, 255, 0.16);
+  --glass: rgba(255, 255, 255, 0.04);
+  --glass-2: rgba(255, 255, 255, 0.07);
+  --radius: 12px;
+  --radius-sm: 8px;
+  --radius-xs: 6px;
+  --sidebar-w: 232px;
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  height: 100%;
+  background: var(--bg);
+  color: var(--text);
+  font-family: 'Geist Sans', -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+a { color: inherit; text-decoration: none; }
+
+.ae-root {
+  display: grid;
+  grid-template-columns: var(--sidebar-w) 1fr;
+  height: 100vh;
+  transition: grid-template-columns 0.18s ease;
+}
+.ae-root.collapsed { grid-template-columns: 60px 1fr; }
+
+/* ── Sidebar ─────────────────────────────────────────────── */
+.ae-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 12px;
+  border-right: 1px solid var(--border);
+  background: var(--surface);
+  min-width: 0;
+}
+.ae-side-top { display: flex; align-items: center; justify-content: space-between; }
+.ae-brand {
+  display: flex; align-items: center; gap: 9px;
+  background: none; border: none; color: var(--text);
+  font-size: 15px; font-weight: 600; letter-spacing: -0.01em;
+  cursor: pointer; padding: 4px; min-width: 0;
+}
+.ae-brand span { white-space: nowrap; overflow: hidden; }
+.ae-collapse, .ae-new, .ae-signin {
+  cursor: pointer; font-family: inherit;
+}
+.ae-collapse {
+  background: none; border: none; color: var(--text-3);
+  padding: 4px; border-radius: var(--radius-xs); display: flex;
+}
+.ae-collapse:hover { color: var(--text); background: var(--glass); }
+.ae-new {
+  display: flex; align-items: center; gap: 8px;
+  margin-top: 8px; padding: 9px 12px;
+  background: var(--text); color: #000; border: none;
+  border-radius: var(--radius-sm); font-size: 13px; font-weight: 600;
+  white-space: nowrap; overflow: hidden;
+}
+.ae-new:hover { background: #fff; }
+.ae-nav { display: flex; flex-direction: column; margin-top: 12px; gap: 1px; }
+.ae-nav a {
+  padding: 8px 10px; border-radius: var(--radius-xs);
+  color: var(--text-2); font-size: 13px; white-space: nowrap;
+}
+.ae-nav a:hover { background: var(--glass); color: var(--text); }
+.ae-side-bottom { margin-top: auto; }
+.ae-signin {
+  width: 100%; padding: 9px 12px;
+  background: var(--glass-2); border: 1px solid var(--border);
+  color: var(--text); border-radius: var(--radius-sm);
+  font-size: 12.5px; font-weight: 500; white-space: nowrap; overflow: hidden;
+}
+.ae-signin:hover { border-color: var(--border-2); background: var(--surface-2); }
+.ae-signin.big { width: auto; padding: 10px 18px; font-size: 14px; }
+.collapsed .ae-brand span, .collapsed .ae-new span, .collapsed .ae-nav { display: none; }
+
+/* ── Main ────────────────────────────────────────────────── */
+.ae-main { min-width: 0; overflow: hidden; display: flex; flex-direction: column; }
+
+/* Hero (empty state) */
+.ae-hero {
+  flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 26px; padding: 24px; overflow-y: auto;
+}
+.ae-wordmark {
+  display: flex; align-items: center; gap: 14px;
+  font-size: 46px; font-weight: 600; letter-spacing: -0.03em; color: var(--text);
+}
+.ae-hero-card { width: 100%; max-width: 720px; }
+.ae-news { width: 100%; max-width: 720px; }
+.ae-news-head, .ae-followups-head, .ae-model-group-label {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.08em;
+  color: var(--text-3); margin-bottom: 10px;
+}
+.ae-news-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }
+.ae-news-item {
+  display: flex; flex-direction: column; gap: 4px;
+  padding: 11px 13px; border: 1px solid var(--border);
+  border-radius: var(--radius-sm); background: var(--surface);
+}
+.ae-news-item:hover { border-color: var(--border-2); background: var(--surface-2); }
+.ae-news-title { font-size: 13px; color: var(--text); line-height: 1.35; }
+.ae-news-meta { font-size: 11px; color: var(--text-3); }
+
+/* ── Input card ──────────────────────────────────────────── */
+.ae-card {
+  background: var(--surface-2);
+  border: 1px solid var(--border-2);
+  border-radius: var(--radius);
+  box-shadow: 0 8px 40px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(255, 255, 255, 0.02);
+  overflow: hidden;
+}
+.ae-input {
+  display: block; width: 100%; resize: none;
+  padding: 16px 18px 6px; min-height: 30px; max-height: 200px;
+  background: transparent; border: none; outline: none;
+  color: var(--text); font-family: inherit; font-size: 15px; line-height: 1.5;
+}
+.ae-input::placeholder { color: var(--text-3); }
+.ae-card-row {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 8px; padding: 8px 10px 10px; flex-wrap: wrap;
+}
+.ae-chips { display: flex; gap: 4px; flex-wrap: wrap; }
+.ae-chip {
+  padding: 4px 9px; border-radius: 999px; cursor: pointer;
+  background: var(--glass); border: 1px solid var(--border);
+  color: var(--text-3); font-size: 11px; font-family: inherit;
+}
+.ae-chip:hover { color: var(--text-2); }
+.ae-chip.on { background: var(--text); color: #000; border-color: var(--text); }
+.ae-card-right { display: flex; align-items: center; gap: 6px; }
+.ae-modes { display: flex; gap: 2px; background: var(--glass); border-radius: var(--radius-xs); padding: 2px; }
+.ae-mode {
+  padding: 4px 9px; border: none; background: none; cursor: pointer;
+  color: var(--text-3); font-size: 11.5px; font-family: inherit; border-radius: 5px;
+}
+.ae-mode:hover { color: var(--text-2); }
+.ae-mode.on { background: var(--surface-3); color: var(--text); }
+.ae-send {
+  width: 34px; height: 34px; flex-shrink: 0; cursor: pointer;
+  display: flex; align-items: center; justify-content: center;
+  background: var(--text); color: #000; border: none; border-radius: 50%;
+}
+.ae-send:disabled { opacity: 0.4; cursor: default; }
+
+/* ── Model picker ────────────────────────────────────────── */
+.ae-picker { position: relative; }
+.ae-picker-btn {
+  display: flex; align-items: center; gap: 6px; cursor: pointer;
+  padding: 6px 10px; background: var(--glass); border: 1px solid var(--border);
+  border-radius: var(--radius-xs); color: var(--text-2); font-size: 12px; font-family: inherit;
+}
+.ae-picker-btn:hover { color: var(--text); border-color: var(--border-2); }
+.ae-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--text-2); }
+.ae-picker-menu {
+  position: absolute; bottom: calc(100% + 6px); right: 0; z-index: 40;
+  width: 320px; max-height: 420px; display: flex; flex-direction: column;
+  background: var(--surface-2); border: 1px solid var(--border-2);
+  border-radius: var(--radius-sm); box-shadow: 0 12px 48px rgba(0, 0, 0, 0.6); overflow: hidden;
+}
+.ae-picker-filter {
+  margin: 8px; padding: 8px 10px; background: var(--bg);
+  border: 1px solid var(--border); border-radius: var(--radius-xs);
+  color: var(--text); font-family: inherit; font-size: 13px; outline: none;
+}
+.ae-picker-list { overflow-y: auto; padding: 0 6px 6px; }
+.ae-model-group-label { padding: 8px 8px 4px; margin: 0; }
+.ae-model-row {
+  display: flex; flex-direction: column; gap: 2px; width: 100%; text-align: left;
+  padding: 8px 10px; background: none; border: none; cursor: pointer;
+  border-radius: var(--radius-xs); color: var(--text); font-family: inherit;
+}
+.ae-model-row:hover { background: var(--glass); }
+.ae-model-row.active { background: var(--glass-2); }
+.ae-model-name { font-size: 13px; display: flex; align-items: center; gap: 7px; }
+.ae-model-desc { font-size: 11px; color: var(--text-3); line-height: 1.3; }
+.ae-badge {
+  font-size: 9px; text-transform: uppercase; letter-spacing: 0.04em;
+  padding: 1px 5px; border-radius: 4px; background: var(--glass-2); color: var(--text-2);
+}
+.ae-plan-banner {
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  padding: 10px 12px; border-top: 1px solid var(--border);
+  font-size: 11.5px; color: var(--text-2); background: var(--surface);
+}
+.ae-plan-tiers { display: flex; gap: 8px; }
+.ae-plan-tier b { color: var(--text); }
+
+/* ── Answer view ─────────────────────────────────────────── */
+.ae-answer-wrap { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+.ae-answer-scroll { flex: 1; overflow-y: auto; padding: 32px 28px 20px; }
+.ae-answer-scroll > * { max-width: 760px; margin-left: auto; margin-right: auto; }
+.ae-question { font-size: 26px; font-weight: 600; letter-spacing: -0.02em; margin: 0 0 20px; }
+.ae-sources { display: flex; gap: 8px; overflow-x: auto; padding-bottom: 16px; margin-bottom: 8px; }
+.ae-source {
+  flex: 0 0 190px; display: flex; flex-direction: column; gap: 6px;
+  padding: 10px 12px; border: 1px solid var(--border); border-radius: var(--radius-sm);
+  background: var(--surface);
+}
+.ae-source:hover { border-color: var(--border-2); background: var(--surface-2); }
+.ae-source-head { display: flex; align-items: center; gap: 6px; }
+.ae-source-head img { border-radius: 3px; }
+.ae-source-host { font-size: 11px; color: var(--text-3); flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ae-source-idx { font-size: 10px; color: var(--text-3); border: 1px solid var(--border); border-radius: 4px; padding: 0 5px; }
+.ae-source-title { font-size: 12.5px; line-height: 1.35; color: var(--text); display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+
+.ae-status { display: flex; align-items: center; gap: 10px; color: var(--text-2); font-size: 14px; padding: 8px 0; }
+
+.ae-answer.markdown { font-size: 15px; line-height: 1.65; color: var(--text); }
+.markdown h2 { font-size: 20px; margin: 22px 0 10px; font-weight: 600; }
+.markdown h3 { font-size: 17px; margin: 18px 0 8px; font-weight: 600; }
+.markdown h4, .markdown h5 { font-size: 15px; margin: 14px 0 6px; font-weight: 600; }
+.markdown p { margin: 0 0 12px; }
+.markdown ul, .markdown ol { margin: 0 0 12px; padding-left: 22px; }
+.markdown li { margin: 4px 0; }
+.markdown a { color: var(--text); text-decoration: underline; text-decoration-color: var(--text-3); text-underline-offset: 2px; }
+.markdown a:hover { text-decoration-color: var(--text); }
+.markdown code { background: var(--surface-2); padding: 1px 5px; border-radius: 4px; font-size: 0.9em; font-family: 'Geist Mono', ui-monospace, monospace; }
+
+.ae-followups { margin-top: 26px; border-top: 1px solid var(--border); padding-top: 16px; }
+.ae-followup {
+  display: flex; align-items: center; justify-content: space-between; width: 100%;
+  padding: 12px 4px; background: none; border: none; border-bottom: 1px solid var(--border);
+  color: var(--text); font-family: inherit; font-size: 14px; text-align: left; cursor: pointer;
+}
+.ae-followup:hover { color: var(--text); }
+.ae-followup:hover .ae-followup-arrow { color: var(--text); transform: translateX(2px); }
+.ae-followup-arrow { color: var(--text-3); transition: transform 0.12s ease; }
+
+.ae-error { color: var(--text-2); padding: 12px 14px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); }
+.ae-auth { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; padding: 8px 0; }
+.ae-auth p { margin: 0; color: var(--text-2); font-size: 15px; }
+
+.ae-answer-composer { padding: 12px 28px 20px; border-top: 1px solid var(--border); background: var(--bg); }
+.ae-answer-composer > .ae-card { max-width: 760px; margin: 0 auto; }
+
+/* ── Spinner ─────────────────────────────────────────────── */
+.ae-spinner {
+  width: 14px; height: 14px; border-radius: 50%; display: inline-block;
+  border: 2px solid var(--border-2); border-top-color: var(--text);
+  animation: ae-spin 0.7s linear infinite;
+}
+@keyframes ae-spin { to { transform: rotate(360deg); } }
+
+@media (max-width: 720px) {
+  .ae-root, .ae-root.collapsed { grid-template-columns: 1fr; }
+  .ae-sidebar { display: none; }
+  .ae-news-grid { grid-template-columns: 1fr; }
+  .ae-hero { gap: 20px; padding: 20px 16px; justify-content: flex-start; padding-top: 48px; }
+  .ae-wordmark { font-size: 34px; }
+  .ae-answer-scroll { padding: 20px 16px 16px; }
+  .ae-answer-composer { padding: 10px 16px 16px; }
+  .ae-question { font-size: 21px; }
+  /* Input card: let the control row wrap so the model picker + send stay
+     reachable at narrow widths (mobile-first). */
+  .ae-card-row { flex-direction: column; align-items: stretch; gap: 10px; }
+  .ae-card-right { justify-content: space-between; }
+  .ae-modes { flex: 1; justify-content: space-between; }
+  .ae-source { flex-basis: 150px; }
+}
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Hanzo</title>
+  <link rel="stylesheet" href="newtab.css" />
+</head>
+<body>
+  <div id="root"></div>
+  <script src="newtab.js"></script>
+</body>
+</html>
@@ -0,0 +1,48 @@
+// Hanzo Answer Engine — new-tab landing + omnibox / address-bar search target.
+// Mounts the shared AnswerEngine React surface; talks to api.hanzo.ai ONLY,
+// through the @hanzo/ai `search` primitive. Auth is brokered by the background
+// (same bridge the popup/sidebar use) so the token never lives in the page.
+import 'webextension-polyfill';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { AnswerEngine } from './answer/AnswerEngine.js';
+import { API_BASE_URL } from './shared/config.js';
+
+declare const browser: typeof chrome;
+const runtime: typeof chrome = (globalThis as any).browser ?? (globalThis as any).chrome;
+
+/** Resolve the IAM bearer via the background broker (null when signed out). */
+async function getToken(): Promise<string | null> {
+  try {
+    const resp: any = await runtime.runtime.sendMessage({ action: 'auth.getToken' });
+    return resp?.token ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function signIn(): void {
+  runtime.runtime.sendMessage({ action: 'auth.login' }).catch(() => {});
+}
+
+function boot() {
+  const params = new URLSearchParams(location.search);
+  const initialQuery = params.get('q') ?? undefined;
+
+  const el = document.getElementById('root');
+  if (!el) return;
+  createRoot(el).render(
+    React.createElement(AnswerEngine, {
+      apiBase: API_BASE_URL,
+      getToken,
+      signIn,
+      ...(initialQuery ? { initialQuery } : {}),
+    }),
+  );
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}
@@ -57,6 +57,18 @@
        <div class="divider"></div>
      </div>

+      <!-- Embedded search: run a query through the Hanzo answer engine. -->
+      <form id="search-form" style="display:flex;gap:6px;margin-bottom:10px;">
+        <input id="search-input" type="text" placeholder="Search Hanzo AI…" autocomplete="off"
+          style="flex:1;min-width:0;padding:9px 12px;background:var(--surface-light,#171717);border:1px solid var(--border,rgba(255,255,255,0.12));border-radius:8px;color:var(--text,#fafafa);font-size:13px;font-family:inherit;outline:none;">
+        <button id="search-btn" type="submit" title="Search" aria-label="Search"
+          style="width:36px;height:36px;flex-shrink:0;display:flex;align-items:center;justify-content:center;background:var(--primary,#fafafa);border:none;border-radius:8px;color:#000;cursor:pointer;">
+          <svg viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.8">
+            <circle cx="7" cy="7" r="4.5"/><path d="M11 11l3.5 3.5" stroke-linecap="round"/>
+          </svg>
+        </button>
+      </form>
+
      <!-- Actions: single Open Chat button + on-page surface settings. -->
      <button id="open-panel" class="btn btn-secondary" style="margin-bottom: 8px;">
        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
@@ -96,6 +108,22 @@

      <div class="divider"></div>

+      <!-- AI Usage (Claude + Codex, from the current browser session) -->
+      <div class="usage-header" style="display:flex;align-items:center;justify-content:space-between;">
+        <h3>AI Usage</h3>
+        <button id="usage-refresh" class="btn-icon" title="Refresh usage">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+            <path d="M23 4v6h-6M1 20v-6h6"/>
+            <path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15"/>
+          </svg>
+        </button>
+      </div>
+      <div id="usage-list" class="usage-list" style="display:flex;flex-direction:column;gap:8px;"></div>
+      <a href="https://console.hanzo.ai/ai-accounts" target="_blank"
+         style="display:inline-block;margin-top:8px;font-size:11px;color:var(--text-muted,#888);">Manage AI accounts →</a>
+
+      <div class="divider"></div>
+
      <!-- Tools -->
      <h3>Tools</h3>
      <div class="tools-grid">
@@ -134,6 +134,19 @@ document.addEventListener('DOMContentLoaded', () => {
    });
  });

+  // --- Embedded search (feature: query → Hanzo answer engine) ---
+  const searchForm = document.getElementById('search-form') as HTMLFormElement | null;
+  const searchInput = document.getElementById('search-input') as HTMLInputElement | null;
+  searchForm?.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const q = searchInput?.value.trim();
+    const target = q
+      ? chrome.runtime.getURL('newtab.html') + '?q=' + encodeURIComponent(q)
+      : chrome.runtime.getURL('newtab.html');
+    chrome.tabs.create({ url: target });
+    window.close();
+  });
+
  // --- Open chat ---
  // Default surface: in-page edge-pinned overlay (content-script). Honours
  // the user's `overlayEnabled`, `overlaySide`, and `overlayWidth` prefs.
@@ -693,6 +706,90 @@ document.addEventListener('DOMContentLoaded', () => {
    });
  });

+  // --- AI Usage (Claude + Codex) — data fetched by the background context
+  // where host permissions attach the live claude.ai / chatgpt.com cookies. ---
+  const usageList = document.getElementById('usage-list');
+  const usageRefresh = document.getElementById('usage-refresh');
+
+  interface UsageWindow { usedPercent: number; resetsAt?: string }
+  interface UsageSnapshotLite {
+    primary?: UsageWindow;
+    secondary?: UsageWindow;
+    identity?: { plan?: string };
+  }
+  interface ProviderUsageLite {
+    providerId: string;
+    displayName: string;
+    color?: string;
+    snapshot?: UsageSnapshotLite;
+    error?: string;
+  }
+
+  const esc = (s: string) =>
+    s.replace(/[&<>"]/g, (c) => (({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }) as Record<string, string>)[c]);
+
+  function resetLabel(iso?: string): string {
+    if (!iso) return '';
+    const ms = new Date(iso).getTime() - Date.now();
+    if (!Number.isFinite(ms)) return '';
+    if (ms <= 0) return 'resets now';
+    const m = Math.round(ms / 60000);
+    if (m < 60) return `resets in ${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 24) return `resets in ${h}h`;
+    return `resets in ${Math.round(h / 24)}d`;
+  }
+
+  function lane(label: string, w: UsageWindow | undefined, color?: string): string {
+    if (!w || typeof w.usedPercent !== 'number') return '';
+    const pct = Math.max(0, Math.min(100, Math.round(w.usedPercent)));
+    return `
+      <div class="usage-lane" style="display:flex;align-items:center;gap:8px;font-size:11px;margin-top:4px;">
+        <span style="width:52px;color:var(--text-muted,#888);">${label}</span>
+        <span style="flex:1;height:6px;border-radius:3px;background:var(--surface-2,#222);overflow:hidden;">
+          <span style="display:block;height:100%;width:${pct}%;background:${color || 'var(--accent,#d97757)'};"></span>
+        </span>
+        <span style="width:34px;text-align:right;">${pct}%</span>
+      </div>`;
+  }
+
+  function renderUsage(providers: ProviderUsageLite[]) {
+    if (!usageList) return;
+    usageList.innerHTML = providers
+      .map((p) => {
+        const body = p.error
+          ? `<div style="font-size:11px;color:var(--text-muted,#888);margin-top:4px;">${esc(p.error)}</div>`
+          : `${lane('Session', p.snapshot?.primary, p.color)}${lane('Weekly', p.snapshot?.secondary, p.color)}
+             <div style="font-size:10px;color:var(--text-muted,#888);margin-top:3px;">${esc(resetLabel(p.snapshot?.primary?.resetsAt))}</div>`;
+        const plan = p.snapshot?.identity?.plan;
+        return `
+          <div class="usage-row" style="padding:8px;border:1px solid var(--border,#2a2a2a);border-radius:8px;">
+            <div style="display:flex;align-items:center;gap:6px;">
+              <span style="width:8px;height:8px;border-radius:50%;background:${p.color || '#888'};"></span>
+              <strong style="font-size:12px;">${esc(p.displayName)}</strong>
+              ${plan ? `<span style="font-size:10px;color:var(--text-muted,#888);">${esc(plan)}</span>` : ''}
+            </div>
+            ${body}
+          </div>`;
+      })
+      .join('');
+  }
+
+  function loadUsage() {
+    if (!usageList) return;
+    usageList.innerHTML = '<div style="font-size:11px;color:var(--text-muted,#888);">Loading…</div>';
+    chrome.runtime.sendMessage({ action: 'usage.fetch' }, (resp) => {
+      if (chrome.runtime.lastError || !resp?.success) {
+        usageList.innerHTML = '<div style="font-size:11px;color:var(--text-muted,#888);">Usage unavailable</div>';
+        return;
+      }
+      renderUsage(resp.providers as ProviderUsageLite[]);
+    });
+  }
+
+  usageRefresh?.addEventListener('click', loadUsage);
+  loadUsage();
+
  // Init
  checkAuth();
 });
@@ -1,47 +1,49 @@
 /**
 * KMS (Key Management / Secrets) client — shared across all browser targets.
 *
- * Lightweight fetch-based client for Hanzo KMS (kms.hanzo.ai).
- * Uses IAM bearer tokens for auth — no separate KMS credentials needed.
+ * Lightweight fetch-based client for Hanzo KMS. Uses IAM bearer tokens for
+ * auth — no separate KMS credentials needed.
 *
- * API path. Hanzo convention is `/v1/<service>/<endpoint>` — but the KMS
- * upstream publishes its v3 API under the root
- * `${KMS_PATH_PREFIX}/secrets/raw`. The kms.hanzo.ai gateway currently passes that
- * through unchanged (verified: `kms.hanzo.ai/api/v3/secrets/raw` → 401 JSON,
- * `/v1/kms/...` → SPA HTML). We centralise the path in `KMS_PATH_PREFIX`
- * so the day the gateway adds the rewrite we update one constant.
+ * Every path is `/v1/kms/...`, which is the Hanzo `/v1/<service>/<endpoint>`
+ * convention and, more importantly, what the server actually serves:
 *
- *   GET    {KMS_PATH_PREFIX}/secrets/raw         → list
- *   GET    {KMS_PATH_PREFIX}/secrets/raw/:name   → get
- *   POST   {KMS_PATH_PREFIX}/secrets/raw/:name   → create
- *   PATCH  {KMS_PATH_PREFIX}/secrets/raw/:name   → update
- *   DELETE {KMS_PATH_PREFIX}/secrets/raw/:name   → delete
+ *   GET    /v1/kms/orgs/{org}/secrets?path=&env=        → list names
+ *   GET    /v1/kms/orgs/{org}/secrets/{path}/{name}?env= → read one value
+ *   POST   /v1/kms/orgs/{org}/secrets                    → create or replace
+ *   DELETE /v1/kms/orgs/{org}/secrets/{path}/{name}?env= → delete
+ *
+ * This file used to speak Infisical's shape under an `/api/v3` prefix, with a
+ * header comment reporting that `/v1/kms/...` had been *verified* to return SPA
+ * HTML while `/api/v3/secrets/raw` returned JSON — so `/api/v3` was pinned as
+ * the working path and a rewrite was awaited. The observation was real and the
+ * conclusion was backwards: the KMS binary embedded a console SPA under a root
+ * catch-all, so it answered EVERY unmatched path with 200 text/html. The HTML
+ * was the 404. luxfi/kms 1.12.8 removed the catch-all, and the same probe now
+ * reads the other way round — `/v1/kms/...` answers JSON, `/api/v3/...` is a
+ * JSON 404. There is no gateway rewrite to wait for.
+ *
+ * Create and update are ONE call because the server has one upsert, not two
+ * endpoints. Listing arrived in luxfi/kms 1.12.9; before that the HTTP surface
+ * had no list at all, which is what made the Infisical prefix look necessary.
 */

 import { KMS_API_URL } from './config.js';

-/** Prefix for every KMS request. See file header. */
-const KMS_PATH_PREFIX = '/api/v3';
-
 // ── Types ───────────────────────────────────────────────────────────────

-export interface KmsSecret {
-  secretKey: string;
-  secretValue?: string;
-  version?: number;
-  type?: string;
-  environment?: string;
-  secretPath?: string;
+/** Where a secret lives. `path` groups secrets; `name` identifies one. */
+export interface KmsRef {
+  /** Org scope — also the scope of the bearer token that reads it. */
+  org: string;
+  /** Environment slug (`dev` / `test` / `main`). Defaults to `default`. */
+  env?: string;
+  /** Grouping path, e.g. `gateway`. Omit to address the org root. */
+  path?: string;
 }

-export interface KmsListParams {
-  workspaceId: string;
-  environment: string;
-  secretPath?: string;
-}
-
-export interface KmsSecretParams extends KmsListParams {
-  secretName: string;
+/** A ref plus the name of a single secret. */
+export interface KmsSecretRef extends KmsRef {
+  name: string;
 }

 // ── Helpers ─────────────────────────────────────────────────────────────
@@ -57,121 +59,94 @@ function kmsUrl(path: string, baseUrl?: string): string {
  return `${baseUrl || KMS_API_URL}${path}`;
 }

-function buildQuery(params: Record<string, string | undefined>): string {
-  const entries = Object.entries(params).filter(([, v]) => v !== undefined) as [string, string][];
-  if (!entries.length) return '';
-  return '?' + new URLSearchParams(entries).toString();
+/** The collection URL for an org, with `path`/`env` as query. */
+function collectionUrl(ref: KmsRef, baseUrl?: string): string {
+  const q = new URLSearchParams();
+  if (ref.path) q.set('path', ref.path);
+  q.set('env', ref.env || 'default');
+  return kmsUrl(`/v1/kms/orgs/${encodeURIComponent(ref.org)}/secrets?${q}`, baseUrl);
+}
+
+/**
+ * The URL of one secret. The server splits the trailing `{rest...}` at its LAST
+ * slash into (path, name), so each segment is escaped on its own — escaping the
+ * joined string would encode the separators and the server would read one long
+ * name.
+ */
+function secretUrl(ref: KmsSecretRef, baseUrl?: string): string {
+  const segs = [...(ref.path ? ref.path.split('/') : []), ref.name]
+    .filter((s) => s.length > 0)
+    .map(encodeURIComponent)
+    .join('/');
+  const q = new URLSearchParams({ env: ref.env || 'default' });
+  return kmsUrl(`/v1/kms/orgs/${encodeURIComponent(ref.org)}/secrets/${segs}?${q}`, baseUrl);
+}
+
+async function fail(op: string, resp: Response): Promise<never> {
+  throw new Error(`KMS ${op} failed: ${resp.status} ${await resp.text()}`);
 }

 // ── API Functions ───────────────────────────────────────────────────────

-/** List secrets in a workspace/environment */
+/** List the names of the secrets under a path. */
 export async function kmsListSecrets(
  token: string,
-  params: KmsListParams,
+  ref: KmsRef,
  baseUrl?: string,
-): Promise<KmsSecret[]> {
-  const query = buildQuery({
-    workspaceId: params.workspaceId,
-    environment: params.environment,
-    secretPath: params.secretPath,
-  });
-  const resp = await fetch(kmsUrl(`${KMS_PATH_PREFIX}/secrets/raw${query}`, baseUrl), {
-    headers: kmsHeaders(token),
-  });
-  if (!resp.ok) throw new Error(`KMS list failed: ${resp.status} ${await resp.text()}`);
+): Promise<string[]> {
+  const resp = await fetch(collectionUrl(ref, baseUrl), { headers: kmsHeaders(token) });
+  if (!resp.ok) return fail('list', resp);
  const data = await resp.json();
-  return data.secrets || data;
+  return data.names ?? [];
 }

-/** Get a single secret by name */
+/** Read one secret's value. */
 export async function kmsGetSecret(
  token: string,
-  params: KmsSecretParams,
+  ref: KmsSecretRef,
  baseUrl?: string,
-): Promise<KmsSecret> {
-  const query = buildQuery({
-    workspaceId: params.workspaceId,
-    environment: params.environment,
-    secretPath: params.secretPath,
-  });
-  const resp = await fetch(
-    kmsUrl(`${KMS_PATH_PREFIX}/secrets/raw/${encodeURIComponent(params.secretName)}${query}`, baseUrl),
-    { headers: kmsHeaders(token) },
-  );
-  if (!resp.ok) throw new Error(`KMS get failed: ${resp.status} ${await resp.text()}`);
+): Promise<string> {
+  const resp = await fetch(secretUrl(ref, baseUrl), { headers: kmsHeaders(token) });
+  if (!resp.ok) return fail('get', resp);
  const data = await resp.json();
-  return data.secret || data;
+  return data.secret?.value ?? '';
 }

-/** Create a new secret */
-export async function kmsCreateSecret(
+/**
+ * Create a secret, or replace it if the name already exists. One call, because
+ * the server has one upsert — there is no separate create and update.
+ */
+export async function kmsPutSecret(
  token: string,
-  params: KmsSecretParams,
+  ref: KmsSecretRef,
  value: string,
  baseUrl?: string,
-): Promise<KmsSecret> {
+): Promise<void> {
  const resp = await fetch(
-    kmsUrl(`${KMS_PATH_PREFIX}/secrets/raw/${encodeURIComponent(params.secretName)}`, baseUrl),
+    kmsUrl(`/v1/kms/orgs/${encodeURIComponent(ref.org)}/secrets`, baseUrl),
    {
      method: 'POST',
      headers: kmsHeaders(token),
      body: JSON.stringify({
-        workspaceId: params.workspaceId,
-        environment: params.environment,
-        secretPath: params.secretPath,
-        secretValue: value,
-        type: 'shared',
+        path: ref.path ?? '',
+        name: ref.name,
+        env: ref.env || 'default',
+        value,
      }),
    },
  );
-  if (!resp.ok) throw new Error(`KMS create failed: ${resp.status} ${await resp.text()}`);
-  const data = await resp.json();
-  return data.secret || data;
+  if (!resp.ok) return fail('put', resp);
 }

-/** Update an existing secret */
-export async function kmsUpdateSecret(
-  token: string,
-  params: KmsSecretParams,
-  value: string,
-  baseUrl?: string,
-): Promise<KmsSecret> {
-  const resp = await fetch(
-    kmsUrl(`${KMS_PATH_PREFIX}/secrets/raw/${encodeURIComponent(params.secretName)}`, baseUrl),
-    {
-      method: 'PATCH',
-      headers: kmsHeaders(token),
-      body: JSON.stringify({
-        workspaceId: params.workspaceId,
-        environment: params.environment,
-        secretPath: params.secretPath,
-        secretValue: value,
-      }),
-    },
-  );
-  if (!resp.ok) throw new Error(`KMS update failed: ${resp.status} ${await resp.text()}`);
-  const data = await resp.json();
-  return data.secret || data;
-}
-
-/** Delete a secret */
+/** Delete a secret. */
 export async function kmsDeleteSecret(
  token: string,
-  params: KmsSecretParams,
+  ref: KmsSecretRef,
  baseUrl?: string,
 ): Promise<void> {
-  const resp = await fetch(
-    kmsUrl(`${KMS_PATH_PREFIX}/secrets/raw/${encodeURIComponent(params.secretName)}`, baseUrl),
-    {
-      method: 'DELETE',
-      headers: kmsHeaders(token),
-      body: JSON.stringify({
-        workspaceId: params.workspaceId,
-        environment: params.environment,
-        secretPath: params.secretPath,
-      }),
-    },
-  );
-  if (!resp.ok) throw new Error(`KMS delete failed: ${resp.status} ${await resp.text()}`);
+  const resp = await fetch(secretUrl(ref, baseUrl), {
+    method: 'DELETE',
+    headers: kmsHeaders(token),
+  });
+  if (!resp.ok) return fail('delete', resp);
 }
@@ -63,7 +63,11 @@ export interface NativeZapState {

 export type Dispatch = (method: string, params: any) => Promise<any> | any;

-const RECONNECT_MS = 3000;
+// Gentle safe poll: with no MCP client running there is no router to reach, so
+// the host connects-then-exits; probe every 30s instead of hammering (and
+// re-launching the native host) every 3s. A live consumer is picked up within
+// one interval.
+const RECONNECT_MS = 30_000;

 /** Connect to zapd via the native host, register as a browser provider, and
 *  dispatch inbound ROUTE commands to the browser. Self-heals on disconnect. */
@@ -0,0 +1,148 @@
+// Usage engine bridge — runs the @hanzo/usage providers inside the extension
+// background context, where host permissions let fetch() attach the user's
+// claude.ai / chatgpt.com session cookies (credentials: 'include') and bypass
+// CORS. There is no filesystem in a browser, so file ops are no-ops and the
+// OAuth/CLI strategies simply report "unavailable": the web strategy carries
+// Claude, and a small local fetch carries Codex (whose provider only ships an
+// auth.json OAuth lane, unusable without disk access).
+
+import {
+  runPipeline,
+  claudeProvider,
+  codexProvider,
+  type UsageHost,
+  type HttpRequest,
+  type HttpResponse,
+  type UsageSnapshot,
+  type RateWindow,
+  type ProviderFetchOutcome,
+} from '@hanzo/usage';
+
+/** Serialisable per-provider result sent to the popup. */
+export interface ProviderUsage {
+  providerId: string;
+  displayName: string;
+  color?: string;
+  dashboardUrl?: string;
+  snapshot?: UsageSnapshot;
+  /** User-facing failure reason (e.g. "Open chatgpt.com to sign in"). */
+  error?: string;
+}
+
+const http = async (req: HttpRequest): Promise<HttpResponse> => {
+  const controller = new AbortController();
+  const timeout = req.timeoutMs
+    ? setTimeout(() => controller.abort(), req.timeoutMs)
+    : undefined;
+  try {
+    const res = await fetch(req.url, {
+      method: req.method ?? 'GET',
+      headers: req.headers,
+      body: req.body,
+      credentials: 'include',
+      signal: controller.signal,
+    });
+    const headers: Record<string, string> = {};
+    res.headers.forEach((v, k) => {
+      headers[k] = v;
+    });
+    return { status: res.status, headers, text: await res.text() };
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+};
+
+/** Browser host: network only; no fs, env, or home directory in an extension. */
+const browserHost: UsageHost = {
+  readTextFile: async () => undefined,
+  listDir: async () => [],
+  writeTextFile: async () => {},
+  http,
+  env: () => undefined,
+  homeDir: () => '',
+  now: () => new Date(),
+};
+
+const isAuthError = (text: string): boolean => /\b(401|403)\b/.test(text);
+
+const outcomeError = (providerHost: string, outcome: ProviderFetchOutcome): string => {
+  const attempt = [...outcome.attempts].reverse().find((a) => a.error);
+  const detail = attempt?.error ?? 'no data';
+  return isAuthError(detail) ? `Open ${providerHost} to sign in` : detail;
+};
+
+const fetchClaude = async (): Promise<ProviderUsage> => {
+  const { displayName, color, dashboardUrl } = claudeProvider.metadata;
+  const base: ProviderUsage = { providerId: 'claude', displayName, color, dashboardUrl };
+  try {
+    // Empty cookieHeader passes the web strategy's `typeof === 'string'` gate;
+    // the real session cookie is attached by credentials: 'include'.
+    const outcome = await runPipeline(claudeProvider, {
+      host: browserHost,
+      sourceMode: 'web',
+      settings: { cookieHeader: '' },
+    });
+    if (outcome.result) return { ...base, snapshot: outcome.result.usage };
+    return { ...base, error: outcomeError('claude.ai', outcome) };
+  } catch (e) {
+    return { ...base, error: e instanceof Error ? e.message : String(e) };
+  }
+};
+
+// Codex wire shape (chatgpt.com/backend-api/wham/usage) — mirrors the private
+// interface in @hanzo/usage's codex provider, mapped onto the package's public
+// UsageSnapshot / RateWindow types.
+interface CodexWindow {
+  used_percent?: number;
+  reset_at?: number;
+  limit_window_seconds?: number;
+}
+interface CodexUsageResponse {
+  plan_type?: string;
+  rate_limit?: { primary_window?: CodexWindow; secondary_window?: CodexWindow };
+}
+
+const toWindow = (w: CodexWindow | undefined): RateWindow | undefined => {
+  if (!w || typeof w.used_percent !== 'number') return undefined;
+  return {
+    usedPercent: w.used_percent,
+    windowMinutes: w.limit_window_seconds ? Math.round(w.limit_window_seconds / 60) : undefined,
+    resetsAt: w.reset_at ? new Date(w.reset_at * 1000).toISOString() : undefined,
+  };
+};
+
+const fetchCodex = async (): Promise<ProviderUsage> => {
+  const { displayName, color, dashboardUrl } = codexProvider.metadata;
+  const base: ProviderUsage = { providerId: 'codex', displayName, color, dashboardUrl };
+  try {
+    const res = await http({
+      url: 'https://chatgpt.com/backend-api/wham/usage',
+      headers: { Accept: 'application/json' },
+      timeoutMs: 30_000,
+    });
+    if (res.status !== 200) {
+      return {
+        ...base,
+        error: isAuthError(String(res.status))
+          ? 'Open chatgpt.com to sign in'
+          : `HTTP ${res.status}`,
+      };
+    }
+    const body = JSON.parse(res.text) as CodexUsageResponse;
+    const snapshot: UsageSnapshot = {
+      providerId: 'codex',
+      primary: toWindow(body.rate_limit?.primary_window),
+      secondary: toWindow(body.rate_limit?.secondary_window),
+      identity: { providerId: 'codex', plan: body.plan_type, loginMethod: 'web' },
+      dataConfidence: 'percentOnly',
+      updatedAt: browserHost.now().toISOString(),
+    };
+    return { ...base, snapshot };
+  } catch (e) {
+    return { ...base, error: e instanceof Error ? e.message : String(e) };
+  }
+};
+
+/** Fetch Claude + Codex usage in parallel from the current browser session. */
+export const fetchAllUsage = async (): Promise<ProviderUsage[]> =>
+  Promise.all([fetchClaude(), fetchCodex()]);
@@ -9,6 +9,10 @@
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
+    "baseUrl": ".",
+    "paths": {
+      "@hanzo/usage": ["../../../../usage/packages/core/dist/index.d.ts"]
+    },
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
@@ -2,8 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
  kmsListSecrets,
  kmsGetSecret,
-  kmsCreateSecret,
-  kmsUpdateSecret,
+  kmsPutSecret,
  kmsDeleteSecret,
 } from '../src/shared/kms';

@@ -24,49 +23,95 @@ function mockResponse(data: any, ok = true, status = 200) {
 }

 const TOKEN = 'test-bearer-token';
-const PARAMS = {
-  workspaceId: 'ws-123',
-  environment: 'production',
-  secretPath: '/app',
-};
+const REF = { org: 'hanzo', env: 'production', path: 'app' };
+const SECRET = { ...REF, name: 'API_KEY' };
+
+function calledUrl(): string {
+  return mockFetch.mock.calls[0][0] as string;
+}
+
+function calledInit(): any {
+  return mockFetch.mock.calls[0][1];
+}

 beforeEach(() => {
  mockFetch.mockReset();
 });

+// ---------------------------------------------------------------------------
+// Path shape — the regression that actually happened
+// ---------------------------------------------------------------------------
+
+describe('KMS paths', () => {
+  it('never emits an /api/ prefix', async () => {
+    // This client used to speak /api/v3/secrets/raw, because the KMS binary
+    // embedded a console SPA under a root catch-all and answered every
+    // unmatched path with 200 text/html — so the wrong path looked alive and
+    // the right one looked broken. Nothing may drift back to it.
+    mockFetch.mockResolvedValue(mockResponse({ names: [] }));
+    await kmsListSecrets(TOKEN, REF);
+    mockFetch.mockResolvedValue(mockResponse({ secret: { value: 'v' } }));
+    await kmsGetSecret(TOKEN, SECRET);
+    mockFetch.mockResolvedValue(mockResponse({}));
+    await kmsPutSecret(TOKEN, SECRET, 'v');
+    mockFetch.mockResolvedValue(mockResponse({}));
+    await kmsDeleteSecret(TOKEN, SECRET);
+
+    expect(mockFetch.mock.calls).toHaveLength(4);
+    for (const [url] of mockFetch.mock.calls) {
+      expect(url).not.toContain('/api/');
+      expect(url).toContain('/v1/kms/');
+    }
+  });
+
+  it('escapes path segments individually so separators survive', async () => {
+    // The server splits {rest...} at its LAST slash into (path, name). Escaping
+    // the joined string would encode the separators into one long name.
+    mockFetch.mockResolvedValue(mockResponse({ secret: { value: 'v' } }));
+    await kmsGetSecret(TOKEN, { org: 'hanzo', env: 'main', path: 'a/b', name: 'C D' });
+    expect(calledUrl()).toContain('/v1/kms/orgs/hanzo/secrets/a/b/C%20D');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // kmsListSecrets
 // ---------------------------------------------------------------------------

 describe('kmsListSecrets', () => {
-  it('sends GET with correct URL and query params', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secrets: [{ secretKey: 'API_KEY' }] }));
-
-    const result = await kmsListSecrets(TOKEN, PARAMS);
-
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('kms.hanzo.ai/api/v3/secrets/raw?');
-    expect(url).toContain('workspaceId=ws-123');
-    expect(url).toContain('environment=production');
-    expect(url).toContain('secretPath=%2Fapp');
-    expect(opts.headers.Authorization).toBe(`Bearer ${TOKEN}`);
-    expect(result).toEqual([{ secretKey: 'API_KEY' }]);
+  it('returns the names array', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ names: ['API_KEY', 'DB_URL'] }));
+    await expect(kmsListSecrets(TOKEN, REF)).resolves.toEqual(['API_KEY', 'DB_URL']);
  });

-  it('uses custom baseUrl when provided', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secrets: [] }));
-
-    await kmsListSecrets(TOKEN, PARAMS, 'https://custom-kms.example.com');
-
-    const [url] = mockFetch.mock.calls[0];
-    expect(url).toContain('custom-kms.example.com/api/v3/secrets/raw');
+  it('addresses the collection with path and env as query, and sends the bearer', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ names: [] }));
+    await kmsListSecrets(TOKEN, REF);
+    expect(calledUrl()).toContain('/v1/kms/orgs/hanzo/secrets?');
+    expect(calledUrl()).toContain('path=app');
+    expect(calledUrl()).toContain('env=production');
+    expect(calledInit().headers.Authorization).toBe(`Bearer ${TOKEN}`);
  });

-  it('throws on non-ok response', async () => {
+  it('defaults env when the ref omits it', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ names: [] }));
+    await kmsListSecrets(TOKEN, { org: 'hanzo' });
+    expect(calledUrl()).toContain('env=default');
+  });
+
+  it('yields an empty array when the server omits names', async () => {
+    mockFetch.mockResolvedValue(mockResponse({}));
+    await expect(kmsListSecrets(TOKEN, REF)).resolves.toEqual([]);
+  });
+
+  it('uses a custom baseUrl when provided', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ names: [] }));
+    await kmsListSecrets(TOKEN, REF, 'https://custom-kms.example.com');
+    expect(calledUrl()).toContain('custom-kms.example.com/v1/kms/orgs/hanzo/secrets');
+  });
+
+  it('throws with the status on failure', async () => {
    mockFetch.mockResolvedValue(mockResponse('Not found', false, 404));
-
-    await expect(kmsListSecrets(TOKEN, PARAMS)).rejects.toThrow('KMS list failed: 404');
+    await expect(kmsListSecrets(TOKEN, REF)).rejects.toThrow('KMS list failed: 404');
  });
 });

@@ -75,78 +120,47 @@ describe('kmsListSecrets', () => {
 // ---------------------------------------------------------------------------

 describe('kmsGetSecret', () => {
-  it('sends GET with encoded secret name', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secret: { secretKey: 'DB_URL', secretValue: 'postgres://...' } }));
-
-    const result = await kmsGetSecret(TOKEN, { ...PARAMS, secretName: 'DB_URL' });
-
-    const [url] = mockFetch.mock.calls[0];
-    expect(url).toContain('/api/v3/secrets/raw/DB_URL');
-    expect(result.secretKey).toBe('DB_URL');
+  it('unwraps secret.value', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ secret: { value: 'postgres://...' } }));
+    await expect(kmsGetSecret(TOKEN, SECRET)).resolves.toBe('postgres://...');
  });

-  it('URL-encodes special characters in secret name', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secret: { secretKey: 'app/key' } }));
-
-    await kmsGetSecret(TOKEN, { ...PARAMS, secretName: 'app/key' });
-
-    const [url] = mockFetch.mock.calls[0];
-    expect(url).toContain('app%2Fkey');
+  it('addresses the secret and carries env', async () => {
+    mockFetch.mockResolvedValue(mockResponse({ secret: { value: 'v' } }));
+    await kmsGetSecret(TOKEN, SECRET);
+    expect(calledUrl()).toContain('/v1/kms/orgs/hanzo/secrets/app/API_KEY');
+    expect(calledUrl()).toContain('env=production');
  });

-  it('throws on non-ok response', async () => {
+  it('throws with the status on failure', async () => {
+    mockFetch.mockResolvedValue(mockResponse('Not found', false, 404));
+    await expect(kmsGetSecret(TOKEN, SECRET)).rejects.toThrow('KMS get failed: 404');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// kmsPutSecret — create and replace are one call, because the server has one
+// ---------------------------------------------------------------------------
+
+describe('kmsPutSecret', () => {
+  it('POSTs to the collection with the flat body the server takes', async () => {
+    mockFetch.mockResolvedValue(mockResponse({}));
+    await kmsPutSecret(TOKEN, SECRET, 'sk-live-123');
+
+    expect(calledUrl()).toContain('/v1/kms/orgs/hanzo/secrets');
+    expect(calledUrl()).not.toContain('API_KEY'); // name is in the body, not the URL
+    expect(calledInit().method).toBe('POST');
+    expect(JSON.parse(calledInit().body)).toEqual({
+      path: 'app',
+      name: 'API_KEY',
+      env: 'production',
+      value: 'sk-live-123',
+    });
+  });
+
+  it('throws with the status on failure', async () => {
    mockFetch.mockResolvedValue(mockResponse('Forbidden', false, 403));
-
-    await expect(kmsGetSecret(TOKEN, { ...PARAMS, secretName: 'X' })).rejects.toThrow('KMS get failed: 403');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// kmsCreateSecret
-// ---------------------------------------------------------------------------
-
-describe('kmsCreateSecret', () => {
-  it('sends POST with correct body', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secret: { secretKey: 'NEW_KEY' } }));
-
-    await kmsCreateSecret(TOKEN, { ...PARAMS, secretName: 'NEW_KEY' }, 'secret-value');
-
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('/api/v3/secrets/raw/NEW_KEY');
-    expect(opts.method).toBe('POST');
-    const body = JSON.parse(opts.body);
-    expect(body.secretValue).toBe('secret-value');
-    expect(body.workspaceId).toBe('ws-123');
-    expect(body.environment).toBe('production');
-    expect(body.type).toBe('shared');
-  });
-
-  it('includes Authorization header', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secret: {} }));
-
-    await kmsCreateSecret(TOKEN, { ...PARAMS, secretName: 'X' }, 'val');
-
-    const [, opts] = mockFetch.mock.calls[0];
-    expect(opts.headers.Authorization).toBe(`Bearer ${TOKEN}`);
-    expect(opts.headers['Content-Type']).toBe('application/json');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// kmsUpdateSecret
-// ---------------------------------------------------------------------------
-
-describe('kmsUpdateSecret', () => {
-  it('sends PATCH with correct body', async () => {
-    mockFetch.mockResolvedValue(mockResponse({ secret: { secretKey: 'KEY' } }));
-
-    await kmsUpdateSecret(TOKEN, { ...PARAMS, secretName: 'KEY' }, 'new-value');
-
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('/api/v3/secrets/raw/KEY');
-    expect(opts.method).toBe('PATCH');
-    const body = JSON.parse(opts.body);
-    expect(body.secretValue).toBe('new-value');
+    await expect(kmsPutSecret(TOKEN, SECRET, 'v')).rejects.toThrow('KMS put failed: 403');
  });
 });

@@ -155,21 +169,16 @@ describe('kmsUpdateSecret', () => {
 // ---------------------------------------------------------------------------

 describe('kmsDeleteSecret', () => {
-  it('sends DELETE with correct body', async () => {
+  it('DELETEs the secret URL', async () => {
    mockFetch.mockResolvedValue(mockResponse({}));
-
-    await kmsDeleteSecret(TOKEN, { ...PARAMS, secretName: 'OLD_KEY' });
-
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('/api/v3/secrets/raw/OLD_KEY');
-    expect(opts.method).toBe('DELETE');
-    const body = JSON.parse(opts.body);
-    expect(body.workspaceId).toBe('ws-123');
+    await kmsDeleteSecret(TOKEN, SECRET);
+    expect(calledInit().method).toBe('DELETE');
+    expect(calledUrl()).toContain('/v1/kms/orgs/hanzo/secrets/app/API_KEY');
+    expect(calledUrl()).toContain('env=production');
  });

-  it('throws on non-ok response', async () => {
-    mockFetch.mockResolvedValue(mockResponse('Server Error', false, 500));
-
-    await expect(kmsDeleteSecret(TOKEN, { ...PARAMS, secretName: 'X' })).rejects.toThrow('KMS delete failed: 500');
+  it('throws with the status on failure', async () => {
+    mockFetch.mockResolvedValue(mockResponse('Forbidden', false, 403));
+    await expect(kmsDeleteSecret(TOKEN, SECRET)).rejects.toThrow('KMS delete failed: 403');
  });
 });
@@ -0,0 +1,15 @@
+# Canva Apps SDK configuration, read by `@canva/cli` (`canva apps preview`).
+# Copy to `.env` and fill in the App ID from your app in the Canva Developer
+# Portal (https://www.canva.com/developers/apps). Never commit `.env`.
+
+# The App ID from the Developer Portal (App details → "App ID").
+CANVA_APP_ID=
+
+# The panel dev server / bundle origin the CLI serves. Default matches build.js
+# output served at localhost:8080; the CLI can also proxy its own dev server.
+CANVA_APP_ORIGIN=http://localhost:8080
+
+# Optional: a backend base if you host a Hanzo-side token exchange. Not required —
+# this app takes a user-pasted hk- key and calls api.hanzo.ai directly via
+# @hanzo/ai, so no backend is needed for the core flow.
+CANVA_BACKEND_HOST=
@@ -0,0 +1,111 @@
+# Hanzo AI for Canva
+
+A Canva **Apps SDK** side-panel app that puts Hanzo's models next to your design.
+Non-designers, marketers, and SMBs — Canva's core audience — get copywriting help
+without leaving the canvas:
+
+- **Generate copy** — headlines, captions, and marketing copy from a short brief.
+- **Rewrite selected text** — tighten, restyle, or restate the text you selected, in place.
+- **Translate** — the selected text into any language, tone preserved.
+- **Content ideas** — a numbered list of angles for a topic; click one to add it.
+- **Ask** — a question about the design or its copy.
+
+It reads the current selection and page via `@canva/design`, runs the model gateway
+through the **published `@hanzo/ai`** headless client over `api.hanzo.ai`, and adds or
+replaces text elements with the result. You paste your own Hanzo `hk-` key; the app
+holds no secret and calls no `/api/` path — only `api.hanzo.ai/v1/...`.
+
+## Architecture — one way to do everything
+
+| Module | Responsibility | Depends on |
+| --- | --- | --- |
+| `src/design-core.ts` | **PURE.** The action catalog, prompt builders, design-context assembly + truncation, and response parsing. No SDK, no DOM. Fully unit-tested. | — |
+| `src/hanzo.ts` | Thin wrapper over `@hanzo/ai` — the only place the model gateway is called. | `@hanzo/ai` |
+| `src/canva.ts` | Thin adapter over `@canva/design` — read the selection, replace it, insert a new text element. | `@canva/design` |
+| `src/config.ts` | Gateway base URL, default model, context budget, `hk-` key guard. | — |
+| `src/app.tsx` | The App UI Kit panel — binds the three above to widgets; holds only UI state. | `@canva/app-ui-kit` |
+| `src/index.tsx` | Entry — mounts `App` under `AppUiProvider`. | `react-dom`, `@canva/app-ui-kit` |
+
+The design-core mirrors [`@hanzo/figma`](../figma)'s design-core so the two design
+apps expose the same five actions with the same context/prompt/parse contracts.
+
+### The read-selection → insert-text flow
+
+1. On mount, `canva.ts` `onSelectionChange` subscribes to `selection.registerOnChange({ scope: 'plaintext' })`. Each change yields a `SelectionSnapshot` (`count`, joined `text`); the panel gates **Rewrite** / **Translate** on `count > 0` and shows a preview of the selected text.
+2. You pick an action, add a brief/question/language as needed, and press **Run**.
+3. `design-core.buildActionMessages(id, inputs, { selection })` resolves the action's task, fences the observed design as **data** (with an honest truncation note if it was cut), and returns the OpenAI-shaped message list.
+4. `hanzo.runChat(messages, { token, model })` calls `@hanzo/ai` `chat.completions.create` (non-streaming) and returns the assistant text.
+5. `design-core.parseCopy` / `parseIdeas` strips code fences, wrapping quotes, and list markers into paste-ready text.
+6. You press **Replace selection** (Rewrite → `canva.replaceSelectedText`, which reads a fresh draft, overwrites `draft.contents[].text`, and `draft.save()`s) or **Add to design** (everything else → `canva.insertText` → `addElementAtCursor` with a new `TextElement`). Ideas insert one line per click.
+
+## Develop locally
+
+Prerequisites: Node 18+, pnpm, and a Canva account.
+
+### 1. Create the app in the Canva Developer Portal
+
+1. Go to <https://www.canva.com/developers/apps> and **Create an app**.
+2. Under **App details**, copy the **App ID**.
+3. Under **Add features → Editing**, enable the app to run in the editor side panel (this app needs the *Design editing* scope: read the selection, add/replace elements).
+4. Under **Configure your app**, set the **Development URL** to the CLI/preview origin (default `http://localhost:8080`).
+
+### 2. Configure
+
+```bash
+cd packages/canva
+cp .env.template .env
+# put your App ID into CANVA_APP_ID
+```
+
+### 3. Install, test, build
+
+```bash
+pnpm install            # from the repo root (workspace)
+pnpm --filter @hanzo/canva test       # vitest — the pure design-core + hanzo shaping
+pnpm --filter @hanzo/canva typecheck  # tsc --noEmit, strict
+pnpm --filter @hanzo/canva build      # esbuild → dist/{index.html,app.js,app.css}
+```
+
+### 4. Preview in Canva
+
+Serve the bundle and point the Developer Portal's Development URL at it. With the
+Canva CLI:
+
+```bash
+npx @canva/cli@latest login
+pnpm --filter @hanzo/canva watch      # rebuilds dist/ on change
+npx @canva/cli@latest apps preview    # opens the app in the Canva editor, hot-reloading
+```
+
+Open any design, launch **Hanzo AI** from the app side panel, paste your `hk-` key,
+pick a model, and run an action. Select text on the canvas to enable **Rewrite** and
+**Translate**.
+
+### Getting a Hanzo `hk-` key
+
+Sign in at <https://hanzo.id> and mint an API key (prefixed `hk-`). The panel
+validates the prefix before use and sends it as the bearer to `api.hanzo.ai`. The key
+lives only in the panel's session state — it is never persisted or bundled.
+
+## Submit to the Canva Apps Marketplace
+
+1. Finish and test the app in preview; ensure `pnpm build` is clean and `dist/` loads.
+2. Host `dist/` on your production origin (behind `hanzoai/ingress` + the `hanzoai/static` plugin — never nginx/caddy) and set the app's production **App source URL** to it.
+3. In the Developer Portal, complete **App listing** (name, icon, description, screenshots) and **Submit for review**.
+4. Canva reviews for the requested scopes (Design editing here) and UX. Address feedback and resubmit; on approval the app is published to the Apps Marketplace.
+
+## Tests
+
+`test/design-core.test.ts` covers the pure core: whitespace collapse, context
+assembly + budget truncation, message fencing (data vs. task, the truncation note,
+the no-context path), the five prompt builders (brief/tweak/language/count/question
+embedding and the count clamp), the `id → messages` path, and the response parsers
+(fence/quote stripping, idempotence, list-marker stripping). `test/hanzo.test.ts`
+asserts the `@hanzo/ai` request shaping against a mock client (model, `stream:false`,
+temperature, messages, abort signal, empty-content error, model listing).
+`test/config.test.ts` covers the `/v1` endpoint builders and the `hk-` key guard.
+
+```
+Test Files  3 passed (3)
+     Tests  40 passed (40)
+```
@@ -0,0 +1,71 @@
+// Build @hanzo/canva into dist/: bundle the App UI Kit side-panel app
+// (src/index.tsx) as ESM for the browser and stamp index.html with the entry. No
+// framework — esbuild + Node stdlib only, mirroring @hanzo/shopify's build. The
+// Canva CLI (`canva apps preview`) serves this dist/ (or points at its own dev
+// server); either way the app is a static bundle Canva loads in the app iframe.
+// Every model call goes to api.hanzo.ai via @hanzo/ai; the app holds no secret —
+// the user pastes their own hk- key.
+//
+//   node build.js            → production build  (dist/index.html, dist/app.js, dist/app.css)
+//   node build.js --watch    → rebuild on change
+
+import esbuild from 'esbuild';
+import { rmSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const watch = process.argv.includes('--watch');
+const src = join(__dirname, 'src');
+const dist = join(__dirname, 'dist');
+
+async function build() {
+  rmSync(dist, { recursive: true, force: true });
+  mkdirSync(dist, { recursive: true });
+
+  // Bundle the panel as ESM for the browser. React + App UI Kit are bundled in
+  // (the page is served standalone, no import map); the App UI Kit stylesheet
+  // import emits dist/app.css.
+  const ctx = await esbuild.context({
+    entryPoints: { app: join(src, 'index.tsx') },
+    outdir: dist,
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    target: ['chrome90', 'edge90', 'firefox90', 'safari15'],
+    jsx: 'automatic',
+    loader: { '.css': 'css', '.svg': 'dataurl', '.png': 'dataurl', '.woff': 'dataurl', '.woff2': 'dataurl' },
+    define: { 'process.env.NODE_ENV': JSON.stringify(watch ? 'development' : 'production') },
+    sourcemap: true,
+    minify: !watch,
+    logLevel: 'info',
+  });
+  await ctx.rebuild();
+
+  // Stamp index.html with the entry.
+  const html = readFileSync(join(src, 'index.html'), 'utf8').split('__ENTRY__').join('app.js');
+  writeFileSync(join(dist, 'index.html'), html);
+
+  console.log('Hanzo AI for Canva built -> dist/  (App: dist/index.html)');
+
+  if (watch) {
+    await ctx.watch();
+    console.log('watching...');
+  } else {
+    await ctx.dispose();
+  }
+}
+
+build()
+  .then(() => {
+    if (!watch && !existsSync(join(dist, 'app.css'))) {
+      // The App UI Kit ships its stylesheet via '@canva/app-ui-kit/styles.css'
+      // (imported in index.tsx); esbuild bundles it to app.css. If a future path
+      // changes, warn rather than ship an unstyled app.
+      console.warn('note: dist/app.css not emitted — check the App UI Kit styles import in index.tsx');
+    }
+  })
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
@@ -0,0 +1,64 @@
+{
+  "name": "@hanzo/canva",
+  "version": "1.0.0",
+  "description": "Hanzo AI for Canva — a side-panel Apps SDK app: generate marketing copy, rewrite the selected text, translate, brainstorm content ideas, and ask about the design. An @canva/app-ui-kit React panel that reads the selection/page via @canva/design and adds/replaces text elements, running the model gateway through the published @hanzo/ai over api.hanzo.ai.",
+  "type": "module",
+  "scripts": {
+    "build": "node build.js",
+    "watch": "node build.js --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hanzo/ai": "^0.2.0",
+    "@hanzo/iam": "^0.13.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "peerDependencies": {
+    "@canva/app-ui-kit": "^5.0.0",
+    "@canva/asset": "^2.0.0",
+    "@canva/design": "^2.0.0"
+  },
+  "devDependencies": {
+    "@canva/app-ui-kit": "^5.12.0",
+    "@canva/asset": "^2.3.0",
+    "@canva/design": "^2.10.0",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "esbuild": "^0.25.8",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "hanzo",
+    "canva",
+    "apps-sdk",
+    "copywriting",
+    "marketing-copy",
+    "translate",
+    "ai",
+    "design",
+    "app-ui-kit"
+  ],
+  "author": "Hanzo AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hanzoai/extension.git",
+    "directory": "packages/canva"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "main": "dist/app.js"
+}
@@ -0,0 +1,266 @@
+// The Hanzo AI assistant panel — a Canva App UI Kit React component. All the
+// logic-heavy work lives in tested, pure modules: the action catalog + prompt
+// assembly + response parsing in design-core.ts, the model call in hanzo.ts
+// (@hanzo/ai), and the design I/O in canva.ts (@canva/design). This component
+// only binds them to App UI Kit widgets and holds the panel's small UI state
+// (the pasted key, the picked model, the chosen action, the instruction, the
+// output). It never speaks to api.hanzo.ai or the Canva SDK directly.
+//
+// Flow: pick an action → (for generate/ideas/ask) type a brief, (for rewrite/
+// translate) select text on the canvas → Run → design-core builds the request
+// from the observed selection/page → hanzo.ts calls the model → design-core
+// parses the reply → the panel shows it and inserts it via canva.ts (replace the
+// selection in place, or add a new text element).
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  Alert,
+  Box,
+  Button,
+  FormField,
+  LoadingIndicator,
+  MultilineInput,
+  Rows,
+  Select,
+  Text,
+  TextInput,
+  Title,
+} from '@canva/app-ui-kit';
+import {
+  buildActionMessages,
+  designActionList,
+  parseCopy,
+  parseIdeas,
+  DESIGN_ACTIONS,
+  type ActionInputs,
+  type DesignActionId,
+  type DesignContext,
+} from './design-core.js';
+import { runChat, listModels } from './hanzo.js';
+import { onSelectionChange, replaceSelectedText, insertText, type SelectionSnapshot } from './canva.js';
+import { isHanzoKey, DEFAULT_MODEL } from './config.js';
+
+// The catalog the panel renders, derived from design-core so labels/flags never
+// drift from what will actually run.
+const ACTIONS = designActionList();
+
+type Status = { tone: 'positive' | 'critical' | 'info'; text: string } | null;
+
+export function App(): JSX.Element {
+  const [key, setKey] = useState('');
+  const [models, setModels] = useState<string[]>([]);
+  const [model, setModel] = useState(DEFAULT_MODEL);
+  const [action, setAction] = useState<DesignActionId>('generate');
+  const [instruction, setInstruction] = useState('');
+  const [language, setLanguage] = useState('Spanish');
+  const [selection, setSelection] = useState<SelectionSnapshot>({ count: 0, text: '' });
+  const [output, setOutput] = useState('');
+  const [ideas, setIdeas] = useState<string[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [status, setStatus] = useState<Status>(null);
+
+  const keyValid = isHanzoKey(key);
+  const spec = DESIGN_ACTIONS[action];
+
+  // Track the live plaintext selection so rewrite/translate know what they act on
+  // and the panel can gate those actions until something is selected.
+  useEffect(() => onSelectionChange(setSelection), []);
+
+  // Load the model catalog once a valid key is pasted (org-scoped by the bearer).
+  useEffect(() => {
+    if (!keyValid) return;
+    let live = true;
+    listModels({ token: key })
+      .then((ids) => {
+        if (!live) return;
+        setModels(ids);
+        if (ids.length && !ids.includes(model)) setModel(ids[0]);
+      })
+      .catch(() => live && setModels([]));
+    return () => {
+      live = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [keyValid, key]);
+
+  // The design context we can observe right now — handed to design-core to fence
+  // as data. The page text is left to a future read; the selection is the field
+  // rewrite/translate act on and is always current.
+  const context = useMemo<DesignContext>(
+    () => ({ selection: selection.text || undefined }),
+    [selection.text],
+  );
+
+  const inputs = useMemo<ActionInputs>(
+    () => ({ instruction, language }),
+    [instruction, language],
+  );
+
+  // canRun encodes the action's preconditions: a valid key, plus a selection for
+  // selection-actions and an instruction for instruction-actions.
+  const missing =
+    !keyValid
+      ? 'Paste your Hanzo hk- key to begin.'
+      : spec.needsSelection && selection.count === 0
+        ? 'Select text on your design to run this action.'
+        : spec.needsInstruction && instruction.trim() === ''
+          ? `Enter ${action === 'ask' ? 'a question' : 'a brief'} to run this action.`
+          : '';
+
+  const run = useCallback(async () => {
+    if (missing) {
+      setStatus({ tone: 'info', text: missing });
+      return;
+    }
+    setBusy(true);
+    setStatus(null);
+    setOutput('');
+    setIdeas([]);
+    try {
+      const messages = buildActionMessages(action, inputs, context);
+      const reply = await runChat(messages, { token: key, model });
+      if (action === 'ideas') {
+        setIdeas(parseIdeas(reply));
+      } else {
+        setOutput(parseCopy(reply));
+      }
+    } catch (e) {
+      setStatus({ tone: 'critical', text: e instanceof Error ? e.message : 'Generation failed' });
+    } finally {
+      setBusy(false);
+    }
+  }, [missing, action, inputs, context, key, model]);
+
+  // Insert the generated copy. Rewrite replaces the selection in place; every
+  // other action adds a new text element at the cursor.
+  const place = useCallback(
+    async (text: string) => {
+      setBusy(true);
+      setStatus(null);
+      try {
+        if (action === 'rewrite') {
+          await replaceSelectedText(text);
+          setStatus({ tone: 'positive', text: 'Replaced the selected text.' });
+        } else {
+          await insertText(text, action === 'generate' ? 32 : 18);
+          setStatus({ tone: 'positive', text: 'Added to your design.' });
+        }
+      } catch (e) {
+        setStatus({ tone: 'critical', text: e instanceof Error ? e.message : 'Could not add to design' });
+      } finally {
+        setBusy(false);
+      }
+    },
+    [action],
+  );
+
+  return (
+    <Box padding="2u">
+      <Rows spacing="2u">
+        <Title size="small">Hanzo AI</Title>
+
+        <FormField
+          label="Hanzo API key"
+          description={keyValid ? 'Key looks valid.' : 'Paste your hk- key from hanzo.id'}
+          control={(props) => (
+            <TextInput {...props} placeholder="hk-..." value={key} onChange={setKey} />
+          )}
+        />
+
+        {models.length > 0 && (
+          <FormField
+            label="Model"
+            control={() => (
+              <Select
+                stretch
+                value={model}
+                onChange={setModel}
+                options={models.map((id) => ({ value: id, label: id }))}
+              />
+            )}
+          />
+        )}
+
+        <FormField
+          label="Action"
+          control={() => (
+            <Select
+              stretch
+              value={action}
+              onChange={(v) => setAction(v as DesignActionId)}
+              options={ACTIONS.map((a) => ({ value: a.id, label: a.label }))}
+            />
+          )}
+        />
+
+        {action === 'translate' ? (
+          <FormField
+            label="Target language"
+            control={(props) => (
+              <TextInput {...props} placeholder="Spanish" value={language} onChange={setLanguage} />
+            )}
+          />
+        ) : spec.needsInstruction ? (
+          <FormField
+            label={action === 'ask' ? 'Question' : action === 'ideas' ? 'Topic' : 'Brief'}
+            control={() => (
+              <MultilineInput
+                autoGrow
+                minRows={2}
+                placeholder={
+                  action === 'ask'
+                    ? 'What tone should this poster use?'
+                    : action === 'ideas'
+                      ? 'Summer sale for a coffee brand'
+                      : 'A bold headline for our spring launch'
+                }
+                value={instruction}
+                onChange={setInstruction}
+              />
+            )}
+          />
+        ) : null}
+
+        {spec.needsSelection && (
+          <Text size="small" tone="tertiary">
+            {selection.count > 0
+              ? `Selected: ${selection.text.slice(0, 80)}${selection.text.length > 80 ? '…' : ''}`
+              : 'Nothing selected — select text on your design.'}
+          </Text>
+        )}
+
+        <Button variant="primary" onClick={() => void run()} disabled={busy} stretch loading={busy}>
+          {spec.label}
+        </Button>
+
+        {busy && <LoadingIndicator />}
+        {status && <Alert tone={status.tone}>{status.text}</Alert>}
+
+        {output && (
+          <Rows spacing="1u">
+            <FormField
+              label="Result"
+              control={() => (
+                <MultilineInput autoGrow minRows={3} value={output} onChange={setOutput} />
+              )}
+            />
+            <Button variant="primary" onClick={() => void place(output)} disabled={busy} stretch>
+              {action === 'rewrite' ? 'Replace selection' : 'Add to design'}
+            </Button>
+          </Rows>
+        )}
+
+        {ideas.length > 0 && (
+          <Rows spacing="1u">
+            <Text size="small" tone="tertiary">Content ideas</Text>
+            {ideas.map((idea, i) => (
+              <Button key={i} variant="secondary" onClick={() => void place(idea)} disabled={busy} stretch>
+                {idea}
+              </Button>
+            ))}
+          </Rows>
+        )}
+      </Rows>
+    </Box>
+  );
+}
@@ -0,0 +1,107 @@
+// The thin adapter over @canva/design — the only place the Canva Apps SDK is
+// touched. It turns Canva's event-driven, draft-based design model into the two
+// operations the panel needs: OBSERVE the current selection (its plaintext + a
+// mutable handle to overwrite it) and INSERT AI output onto the canvas (add a new
+// text element, or replace the selected text in place). All the AI logic lives in
+// design-core.ts (pure) and hanzo.ts (@hanzo/ai); this module carries no prompts
+// and no model calls — it is pure design I/O.
+//
+// Canva's contract (@canva/design 2.x):
+//   - `selection.registerOnChange({ scope: 'plaintext', onChange })` fires with a
+//     `count` and a `read()` that yields a draft whose `contents[].text` are the
+//     selected text runs; mutating them and `draft.save()` writes them back.
+//   - `addElementAtCursor(textElement)` / `addNativeElement(textElement)` add a
+//     new text element at the user's cursor / onto the current page.
+//   - `getCurrentPageContext()` yields the page dimensions (used only to size a
+//     from-scratch insert sensibly).
+
+import {
+  selection,
+  addElementAtCursor,
+  type TextElement,
+} from '@canva/design';
+
+// ---- Selection observation ------------------------------------------------
+
+// SelectionSnapshot is what the panel needs to reason about the current
+// selection without holding a Canva draft: how many text elements are selected
+// and their combined plaintext (for context assembly and for showing the user
+// what rewrite/translate will act on). A draft is short-lived and must be
+// re-read at write time, so we never stash it — see replaceSelectedText.
+export interface SelectionSnapshot {
+  /** Number of selected plaintext elements. 0 means nothing text is selected. */
+  count: number;
+  /** The selected text runs joined with newlines — '' when count is 0. */
+  text: string;
+}
+
+// onSelectionChange subscribes to plaintext selection changes and calls back with
+// a SelectionSnapshot each time. It reads the draft only to extract the text (it
+// never mutates or saves here) and returns the SDK's unsubscribe function so the
+// panel can tear the listener down on unmount. This is the panel's single source
+// of "what is selected right now".
+export function onSelectionChange(cb: (snap: SelectionSnapshot) => void): () => void {
+  return selection.registerOnChange({
+    scope: 'plaintext',
+    onChange: async (event) => {
+      if (event.count === 0) {
+        cb({ count: 0, text: '' });
+        return;
+      }
+      const draft = await event.read();
+      const text = draft.contents.map((c) => c.text).join('\n');
+      cb({ count: event.count, text });
+    },
+  });
+}
+
+// ---- Writing output onto the canvas ---------------------------------------
+
+// replaceSelectedText overwrites the currently-selected plaintext with `text`.
+// Canva requires the write to happen inside a fresh draft read (the snapshot the
+// panel holds may be stale), so we register a one-shot listener, read the current
+// draft, write every selected run — the first run gets the full replacement and
+// any further runs are cleared so N selected elements collapse to the one new
+// value — save, and unsubscribe. Resolves once saved; rejects if nothing is
+// selected when the write is attempted.
+export function replaceSelectedText(text: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let done = false;
+    const unsubscribe = selection.registerOnChange({
+      scope: 'plaintext',
+      onChange: async (event) => {
+        if (done) return;
+        done = true;
+        try {
+          if (event.count === 0) {
+            reject(new Error('No text is selected to replace'));
+            return;
+          }
+          const draft = await event.read();
+          draft.contents.forEach((c, i) => {
+            c.text = i === 0 ? text : '';
+          });
+          await draft.save();
+          resolve();
+        } catch (e) {
+          reject(e instanceof Error ? e : new Error(String(e)));
+        } finally {
+          unsubscribe();
+        }
+      },
+    });
+  });
+}
+
+// insertText adds a new text element carrying `text` at the user's cursor. Used
+// for generate / ideas / translate-as-new — anything that adds copy rather than
+// editing the selection. `fontSize` sizes it (a headline larger than a caption);
+// Canva positions it at the cursor.
+export function insertText(text: string, fontSize = 24): Promise<void> {
+  const element: TextElement = {
+    type: 'text',
+    children: [text],
+    fontSize,
+  };
+  return addElementAtCursor(element);
+}
@@ -0,0 +1,50 @@
+// Canva app config — the api.hanzo.ai model gateway (default model + endpoints)
+// and the design-context character budget. Endpoints and the bearer choice
+// mirror @hanzo/shopify / @hanzo/figma so the productivity suite stays DRY; the
+// design-specific pieces (context assembly, the AI actions, response parsing)
+// live in design-core.ts, and the two thin adapters — @hanzo/ai in hanzo.ts and
+// @canva/design in canva.ts — carry the I/O.
+
+// ---- Hanzo model gateway --------------------------------------------------
+
+// Where the Hanzo model gateway lives. `@hanzo/ai` (createAiClient) defaults
+// here too. /v1 only, never an /api/ prefix (api.hanzo.ai IS the api host).
+export const HANZO_API_BASE_URL = 'https://api.hanzo.ai';
+
+// Default model. A Zen model (qwen3+). Overridable per-request via the picker;
+// the gateway routes it.
+export const DEFAULT_MODEL = 'zen5';
+
+// Public IAM origin that mints Hanzo user tokens, and the OAuth client id an
+// inbound Hanzo token is audienced to (owner-scoping validation via @hanzo/iam).
+// The Canva app itself pastes an `hk-` key; these exist so a Hanzo-hosted
+// backend can validate one under the shared <org>-<app> naming scheme.
+export const DEFAULT_IAM_SERVER_URL = 'https://hanzo.id';
+export const DEFAULT_IAM_CLIENT_ID = 'hanzo-canva';
+
+// chatCompletionsURL / modelsURL — the model gateway endpoints. The client
+// (createAiClient) builds these itself; these exist for tests + honest docs.
+export function chatCompletionsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/chat/completions`;
+}
+export function modelsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/models`;
+}
+
+// ---- Design context budget ------------------------------------------------
+//
+// A Canva design's on-page text (the selection plus the surrounding page text
+// we assemble as context) can run long — a poster's body copy, a slide's notes.
+// This caps the characters of design context we attach to any one request so it
+// fits comfortably in a model window alongside the reply. Honest truncation,
+// never silent drop (design-core marks `truncated`).
+export const DESIGN_CHAR_BUDGET = 12_000;
+
+// A Hanzo API key is minted by hanzo.id and is always prefixed `hk-`. isHanzoKey
+// is the boundary guard: the panel validates a pasted key against this before it
+// is ever handed to the client as a bearer, so an obviously-wrong paste (an IAM
+// JWT, an OpenAI `sk-` key) is rejected in the UI instead of failing opaquely at
+// the gateway. Trim first — users paste with trailing whitespace.
+export function isHanzoKey(key: string | undefined | null): key is string {
+  return typeof key === 'string' && /^hk-[A-Za-z0-9._-]{16,}$/.test(key.trim());
+}
@@ -0,0 +1,335 @@
+// The design action catalog and everything pure around it: the prompt builders
+// for copy / rewrite / translate / ideas / ask, the design-context assembly and
+// truncation, the message shaping @hanzo/ai takes, and the response parsing that
+// turns a model reply into paste-ready text. NO @canva imports, NO @hanzo/ai
+// imports, NO DOM — this module is host-agnostic and fully unit-testable. The
+// panel (app.tsx) reads a selection / page via canva.ts, hands the text here to
+// build a request, sends it through hanzo.ts, and parses the reply back here
+// before inserting it via canva.ts.
+//
+// It mirrors @hanzo/figma's design-core so the two design apps stay consistent:
+// the same five action families, the same context/prompt/parse contracts. There
+// is exactly ONE code path from an (action id + inputs) to a message list, and
+// ONE path from a raw reply to paste-ready text.
+
+// A message in the OpenAI-compatible schema — the shape @hanzo/ai's
+// chat.completions.create takes. A local alias so the pure builders have a
+// precise, testable return type independent of the SDK's broader union.
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+// SYSTEM_PROMPT grounds every answer in the design context provided. It forbids
+// inventing facts about the brand or product (the failure mode that makes a
+// marketing assistant dangerous — fake claims, fake prices, fake stats), and
+// keeps output ready to drop onto the canvas. Brand-neutral, designer-facing.
+export const SYSTEM_PROMPT =
+  'You are Hanzo AI, a copywriting assistant embedded in Canva. You help create ' +
+  'marketing copy — headlines, captions, body copy, calls to action — and edit ' +
+  'the text already on the design. Work from the design context provided below; ' +
+  'never invent facts, prices, statistics, dates, or claims that are not ' +
+  'supported by it or by the user\'s instruction. Write in clear, natural, ' +
+  'on-brand prose sized for a design surface — punchy for headlines, concise for ' +
+  'captions. Return ONLY the requested text, ready to drop onto the canvas — no ' +
+  'preamble, no explanation, no surrounding quotes, no markdown fences.';
+
+// ---- Design context assembly ----------------------------------------------
+//
+// The panel gathers what it can see about the design — the selected text (the
+// primary subject of rewrite/translate) and the other text on the current page
+// (surrounding voice/context) — and hands it here as a DesignContext. We render
+// it into a compact, labeled block the model reads as data (never as
+// instructions), and cap the whole block at the budget. Honest truncation.
+
+// What the panel can observe about the design and pass to a prompt builder. All
+// fields optional: a blank design has none, a fresh "generate" has only a brief.
+export interface DesignContext {
+  /** The user's selected text — the subject of rewrite/translate. */
+  selection?: string;
+  /** Other text on the current page, in reading order — surrounding voice. */
+  pageText?: string[];
+  /** The design's title, if the app can read it. */
+  title?: string;
+}
+
+// The result of rendering a DesignContext down to what we attach: the text and
+// whether anything was truncated (so the prompt and UI can say so honestly).
+export interface RenderedContext {
+  text: string;
+  truncated: boolean;
+}
+
+// collapseWhitespace normalizes a text fragment for the context block: collapse
+// runs of whitespace (including the newlines Canva stores between text lines)
+// into single spaces and trim. Pure. The model does not need the layout, and
+// raw newlines waste budget and blur the data/instruction boundary.
+export function collapseWhitespace(s: string): string {
+  return s.replace(/\s+/g, ' ').trim();
+}
+
+// buildDesignContext renders the observable design into a labeled block, capped
+// at `budget` characters. The selection is the field the model most needs (it is
+// what rewrite/translate act on), so it is rendered first and the surrounding
+// page text — the longest, least essential field — is what truncation trims.
+// Pure and total. `truncated` is true whenever the render was cut to fit.
+export function buildDesignContext(ctx: DesignContext, budget: number = DESIGN_CHAR_BUDGET): RenderedContext {
+  const lines: string[] = [];
+  if (ctx.title) {
+    const t = collapseWhitespace(ctx.title);
+    if (t) lines.push(`Design title: ${t}`);
+  }
+  if (ctx.selection) {
+    const sel = collapseWhitespace(ctx.selection);
+    if (sel) lines.push(`Selected text: ${sel}`);
+  }
+  if (ctx.pageText && ctx.pageText.length) {
+    const page = ctx.pageText.map(collapseWhitespace).filter(Boolean);
+    if (page.length) lines.push(`Other text on this page: ${page.join(' | ')}`);
+  }
+
+  const full = lines.join('\n');
+  if (full.length <= budget) return { text: full, truncated: false };
+  return { text: full.slice(0, budget), truncated: true };
+}
+
+// DESIGN_CHAR_BUDGET default mirrors config.ts. Re-declared here as the builder's
+// own default so design-core stays importable with zero config dependency (the
+// panel passes the config value explicitly when it wants to; tests do not).
+const DESIGN_CHAR_BUDGET = 12_000;
+
+// ---- Prompt assembly ------------------------------------------------------
+
+// contextNote is the one honest sentence prepended when the render was cut, so
+// the model does not answer as though it saw the whole design.
+function contextNote(truncated: boolean): string {
+  return truncated
+    ? 'Note: the design context below was truncated to fit — answer only from what is shown.'
+    : '';
+}
+
+// buildMessages fences the design context as DATA (never instructions) and rides
+// the honest note inside the user turn so it is never lost. The task (the
+// resolved action prompt, plus any user instruction) comes last. Pure — the
+// whole prompt is asserted in a test. When there is no context (a from-scratch
+// generate with only a brief), the fence is omitted so the user turn is just the
+// task.
+export function buildMessages(task: string, rendered: RenderedContext): ChatMessage[] {
+  const system: ChatMessage = { role: 'system', content: SYSTEM_PROMPT };
+  const note = contextNote(rendered.truncated);
+  const notePrefix = note ? `${note}\n\n` : '';
+  const fence = rendered.text
+    ? `---- design ----\n${rendered.text}\n---- end design ----\n\n`
+    : '';
+  const user: ChatMessage = {
+    role: 'user',
+    content: `${notePrefix}${fence}---- task ----\n${task}`,
+  };
+  return [system, user];
+}
+
+// ---- The action catalog ---------------------------------------------------
+//
+// An action is (id → label + a prompt builder). The builder takes the action's
+// inputs (a brief, a target language, a topic) and returns the task string that
+// is layered onto the fenced context by buildMessages. Some actions ignore the
+// context (generate, ideas, ask-with-no-selection); some require the selection
+// (rewrite, translate). Keeping each action's task in one builder means the
+// panel, the picker, and any test resolve prompts one way.
+
+// The inputs a design action may take. All optional; each builder reads only the
+// fields it needs and ignores the rest. `instruction` is the user's freeform
+// text (the brief for generate, the question for ask, the tweak for rewrite);
+// `language` is the target for translate; `count` bounds an ideas list.
+export interface ActionInputs {
+  instruction?: string;
+  language?: string;
+  count?: number;
+}
+
+// clampCount bounds an ideas request to a sane, promptable range. Pure.
+function clampCount(count: number | undefined): number {
+  if (!count || !Number.isFinite(count)) return 5;
+  return Math.max(1, Math.min(10, Math.floor(count)));
+}
+
+// The five design actions. Each `build` returns the task string. `needsSelection`
+// marks the actions that operate on the selected text (the panel disables them
+// until something is selected). `needsInstruction` marks the actions that
+// require a user brief/question (generate, ask) so the panel can validate before
+// sending. Frozen so the catalog is immutable at runtime.
+export const DESIGN_ACTIONS = {
+  generate: {
+    label: 'Generate copy',
+    needsSelection: false,
+    needsInstruction: true,
+    build: (i: ActionInputs): string => {
+      const brief = (i.instruction ?? '').trim();
+      return (
+        `Write marketing copy for this design based on the brief: "${brief}". ` +
+        'Return polished, on-brand copy sized for a design surface — a headline, ' +
+        'a short caption, or a few tight lines as the brief implies. Ground every ' +
+        'claim in the brief and the design context. Return only the copy.'
+      );
+    },
+  },
+  rewrite: {
+    label: 'Rewrite selected text',
+    needsSelection: true,
+    needsInstruction: false,
+    build: (i: ActionInputs): string => {
+      const tweak = (i.instruction ?? '').trim();
+      const how = tweak
+        ? `Rewrite it as follows: ${tweak}.`
+        : 'Rewrite it to be clearer, tighter, and more persuasive, keeping the same meaning and roughly the same length.';
+      return (
+        `Rewrite the selected text above. ${how} Do NOT add any fact not present ` +
+        'in the design context or the instruction. Return only the rewritten text.'
+      );
+    },
+  },
+  translate: {
+    label: 'Translate',
+    needsSelection: true,
+    needsInstruction: false,
+    build: (i: ActionInputs): string => {
+      const lang = (i.language ?? '').trim() || 'Spanish';
+      return (
+        `Translate the selected text above into ${lang}. Preserve the tone, ` +
+        'intent, and any brand names verbatim; localize idioms naturally rather ' +
+        'than translating word for word. Return only the translated text.'
+      );
+    },
+  },
+  ideas: {
+    label: 'Content ideas',
+    needsSelection: false,
+    needsInstruction: true,
+    build: (i: ActionInputs): string => {
+      const topic = (i.instruction ?? '').trim();
+      const n = clampCount(i.count);
+      return (
+        `Suggest ${n} distinct content ideas for this design about: "${topic}". ` +
+        'Each idea a single short line (a headline or angle), grounded in the ' +
+        'topic and the design context. Return a numbered list, nothing else.'
+      );
+    },
+  },
+  ask: {
+    label: 'Ask',
+    needsSelection: false,
+    needsInstruction: true,
+    build: (i: ActionInputs): string => {
+      const q = (i.instruction ?? '').trim();
+      return (
+        `Answer this question about the design or its copy: "${q}". Answer only ` +
+        'from the design context and general copywriting knowledge; if the ' +
+        'context does not support an answer, say so plainly.'
+      );
+    },
+  },
+} as const;
+
+// A design action id from the catalog.
+export type DesignActionId = keyof typeof DESIGN_ACTIONS;
+
+// isDesignActionId narrows an arbitrary string to a known id. Boundary guard —
+// the panel validates an inbound id here before running it.
+export function isDesignActionId(id: string): id is DesignActionId {
+  return Object.prototype.hasOwnProperty.call(DESIGN_ACTIONS, id);
+}
+
+// designActionList is the ordered catalog for building the UI, derived from the
+// action map so the panel and the catalog can never drift.
+export function designActionList(): Array<{
+  id: DesignActionId;
+  label: string;
+  needsSelection: boolean;
+  needsInstruction: boolean;
+}> {
+  return (Object.keys(DESIGN_ACTIONS) as DesignActionId[]).map((id) => {
+    const a = DESIGN_ACTIONS[id];
+    return { id, label: a.label, needsSelection: a.needsSelection, needsInstruction: a.needsInstruction };
+  });
+}
+
+// actionTask resolves an id + inputs to its task string. Throws on an unknown id
+// (a boundary error surfaced to the caller) rather than silently running a
+// default. This is the single id→prompt resolution the panel calls.
+export function actionTask(id: string, inputs: ActionInputs = {}): string {
+  if (!isDesignActionId(id)) throw new Error(`Unknown design action: ${id}`);
+  return DESIGN_ACTIONS[id].build(inputs);
+}
+
+// buildActionMessages is the single path from an (action id, inputs, observed
+// design) to the message list @hanzo/ai takes. Resolve the task, render the
+// context, assemble the messages. Pure — the whole request is asserted in a
+// test. The panel calls exactly this, then hands the result to hanzo.ts.
+export function buildActionMessages(
+  id: string,
+  inputs: ActionInputs,
+  ctx: DesignContext,
+  budget: number = DESIGN_CHAR_BUDGET,
+): ChatMessage[] {
+  const task = actionTask(id, inputs);
+  return buildMessages(task, buildDesignContext(ctx, budget));
+}
+
+// ---- Response parsing -----------------------------------------------------
+//
+// Models sometimes wrap paste-ready text despite the system prompt: a leading
+// "Here's your headline:", a Markdown code fence, or matched surrounding quotes.
+// parseCopy strips those so the text drops cleanly onto the canvas. Total and
+// idempotent — parsing already-clean text returns it unchanged.
+
+// stripFence removes a single wrapping Markdown code fence (```lang ... ```) if
+// the whole reply is fenced. It does NOT touch fences in the middle of a reply
+// (those are intentional content). Pure.
+function stripFence(s: string): string {
+  const m = s.match(/^```[^\n]*\n([\s\S]*?)\n?```$/);
+  return m ? m[1] : s;
+}
+
+// stripWrappingQuotes removes one matched pair of surrounding quotes (straight or
+// curly) when the ENTIRE string is quoted — the model quoting a headline. It
+// leaves quotes that are part of the content (an opening quote with no close, an
+// internal quote). Pure.
+function stripWrappingQuotes(s: string): string {
+  const pairs: Array<[string, string]> = [
+    ['"', '"'],
+    ["'", "'"],
+    ['“', '”'],
+    ['‘', '’'],
+  ];
+  for (const [open, close] of pairs) {
+    if (s.length >= 2 && s.startsWith(open) && s.endsWith(close)) {
+      const inner = s.slice(1, -1);
+      // Only strip if the inner text has no unescaped copy of the closing quote,
+      // i.e. the quotes truly wrap the whole thing rather than being content.
+      if (!inner.includes(close)) return inner;
+    }
+  }
+  return s;
+}
+
+// parseCopy turns a raw model reply into paste-ready text: trim, drop a single
+// wrapping code fence, drop matched surrounding quotes, trim again. Idempotent.
+// This is the single reply→text path the panel uses before inserting.
+export function parseCopy(raw: string): string {
+  let s = raw.trim();
+  s = stripFence(s).trim();
+  s = stripWrappingQuotes(s).trim();
+  return s;
+}
+
+// parseIdeas turns a raw "ideas" reply — a numbered or bulleted list — into a
+// clean array of idea lines, dropping the list markers so each idea can be shown
+// as its own item and inserted individually. Pure. Blank lines and pure-marker
+// lines are dropped; a reply with no list structure yields its non-empty lines.
+export function parseIdeas(raw: string): string[] {
+  return raw
+    .split('\n')
+    .map((line) => line.replace(/^\s*(?:\d+[.)]|[-*•])\s+/, '').trim())
+    .map((line) => stripWrappingQuotes(line).trim())
+    .filter((line) => line.length > 0);
+}
@@ -0,0 +1,58 @@
+// The single call path to the model — a THIN wrapper over the PUBLISHED headless
+// client `@hanzo/ai` (createAiClient). We do NOT reimplement the transport. This
+// module owns only client construction (token + baseURL wiring) and the two
+// primitives the panel needs: run a built message list to text, and list models.
+// The design-aware layer (context, prompts, parsing) is entirely in
+// design-core.ts; the Canva-aware layer (read selection, insert text) is in
+// canva.ts. Both are pure of the SDK; this is the only place the SDK is called.
+
+import { createAiClient, type AiClient } from '@hanzo/ai';
+import { DEFAULT_MODEL, HANZO_API_BASE_URL } from './config.js';
+import type { ChatMessage } from './design-core.js';
+
+export interface AskOptions {
+  model?: string;
+  temperature?: number;
+  /** Hanzo `hk-` key pasted by the user; sent as the bearer. */
+  token?: string;
+  baseURL?: string;
+  /** Injected client (tests). Defaults to a real createAiClient. */
+  client?: AiClient;
+  signal?: AbortSignal;
+}
+
+// client resolves an AiClient: the injected one (tests) or a real published
+// @hanzo/ai client pointed at the gateway with the caller's bearer. One place
+// constructs it so the token/baseURL wiring is identical for every call.
+function client(opts: AskOptions): AiClient {
+  return opts.client ?? createAiClient({ token: opts.token, baseUrl: opts.baseURL ?? HANZO_API_BASE_URL });
+}
+
+// runChat is the single path from a built message list to the model. Every Canva
+// surface (every action) funnels here. Non-streaming: the panel renders the
+// final text and inserts it. token may be empty (the gateway serves anonymous/
+// limited models), but the panel gates on a valid `hk-` key first.
+export async function runChat(messages: ChatMessage[], opts: AskOptions = {}): Promise<string> {
+  const res = await client(opts).chat.completions.create(
+    {
+      model: opts.model ?? DEFAULT_MODEL,
+      messages,
+      temperature: opts.temperature,
+      stream: false,
+    },
+    { signal: opts.signal },
+  );
+  const content = res.choices?.[0]?.message?.content;
+  if (typeof content !== 'string' || content === '') {
+    throw new Error('Hanzo API returned no content');
+  }
+  return content;
+}
+
+// listModels returns the model ids the caller may route to, from /v1/models via
+// the headless client. Org-scoped by the bearer; an empty token lists public
+// models.
+export async function listModels(opts: AskOptions = {}): Promise<string[]> {
+  const models = await client(opts).models.list({ signal: opts.signal });
+  return models.map((m) => m.id);
+}
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hanzo AI for Canva</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="__ENTRY__"></script>
+  </body>
+</html>
@@ -0,0 +1,19 @@
+// The Canva app entry — mounts the App UI Kit panel into the side-panel root
+// under AppUiProvider (which supplies the Canva theme + tokens the App UI Kit
+// components read). Canva loads this bundle in the app iframe; the element with
+// id `root` is the panel's mount point (see index.html). This file is the ONLY
+// DOM entry — all UI is in app.tsx, all logic in the pure/thin modules.
+
+import { createRoot } from 'react-dom/client';
+import { AppUiProvider } from '@canva/app-ui-kit';
+import '@canva/app-ui-kit/styles.css';
+import { App } from './app.js';
+
+const root = document.getElementById('root');
+if (!root) throw new Error('Missing #root mount element');
+
+createRoot(root).render(
+  <AppUiProvider>
+    <App />
+  </AppUiProvider>,
+);
@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import {
+  HANZO_API_BASE_URL,
+  DEFAULT_MODEL,
+  chatCompletionsURL,
+  modelsURL,
+  isHanzoKey,
+} from '../src/config';
+
+describe('gateway config', () => {
+  it('points at api.hanzo.ai with /v1 endpoints (never /api/)', () => {
+    expect(HANZO_API_BASE_URL).toBe('https://api.hanzo.ai');
+    expect(chatCompletionsURL()).toBe('https://api.hanzo.ai/v1/chat/completions');
+    expect(modelsURL()).toBe('https://api.hanzo.ai/v1/models');
+    expect(chatCompletionsURL()).not.toContain('/api/');
+  });
+
+  it('defaults to a Zen model', () => {
+    expect(DEFAULT_MODEL).toBe('zen5');
+  });
+});
+
+describe('isHanzoKey', () => {
+  it('accepts a well-formed hk- key (trimming whitespace)', () => {
+    expect(isHanzoKey('hk-abcdef0123456789ABCDEF')).toBe(true);
+    expect(isHanzoKey('  hk-abcdef0123456789ABCDEF  ')).toBe(true);
+  });
+
+  it('rejects the wrong prefix, too-short, or non-string', () => {
+    expect(isHanzoKey('sk-abcdef0123456789ABCDEF')).toBe(false);
+    expect(isHanzoKey('hk-short')).toBe(false);
+    expect(isHanzoKey('')).toBe(false);
+    expect(isHanzoKey(undefined)).toBe(false);
+    expect(isHanzoKey(null)).toBe(false);
+  });
+});
@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import {
+  SYSTEM_PROMPT,
+  collapseWhitespace,
+  buildDesignContext,
+  buildMessages,
+  buildActionMessages,
+  DESIGN_ACTIONS,
+  designActionList,
+  isDesignActionId,
+  actionTask,
+  parseCopy,
+  parseIdeas,
+  type ChatMessage,
+  type DesignContext,
+} from '../src/design-core';
+
+describe('collapseWhitespace', () => {
+  it('collapses runs of whitespace and newlines and trims', () => {
+    expect(collapseWhitespace('  a\n\n  b\t c  ')).toBe('a b c');
+  });
+  it('is idempotent on clean text', () => {
+    expect(collapseWhitespace('already clean')).toBe('already clean');
+  });
+});
+
+describe('buildDesignContext', () => {
+  it('renders title, selection, then page text as labeled data', () => {
+    const ctx: DesignContext = {
+      title: 'Spring Launch',
+      selection: 'Big  savings\nthis week',
+      pageText: ['Shop now', '  Limited  time '],
+    };
+    const r = buildDesignContext(ctx);
+    expect(r.truncated).toBe(false);
+    expect(r.text).toContain('Design title: Spring Launch');
+    expect(r.text).toContain('Selected text: Big savings this week');
+    expect(r.text).toContain('Other text on this page: Shop now | Limited time');
+    // Selection comes before page text (it is what the model most needs).
+    expect(r.text.indexOf('Selected text')).toBeLessThan(r.text.indexOf('Other text on this page'));
+  });
+
+  it('omits absent fields and yields empty text for an empty design', () => {
+    expect(buildDesignContext({})).toEqual({ text: '', truncated: false });
+    const onlySel = buildDesignContext({ selection: 'x' });
+    expect(onlySel.text).toBe('Selected text: x');
+  });
+
+  it('drops blank page-text entries', () => {
+    const r = buildDesignContext({ pageText: ['', '   ', 'kept'] });
+    expect(r.text).toBe('Other text on this page: kept');
+  });
+
+  it('truncates to the budget and flags it', () => {
+    const r = buildDesignContext({ selection: 'x'.repeat(100) }, 40);
+    expect(r.truncated).toBe(true);
+    expect(r.text.length).toBe(40);
+  });
+});
+
+describe('buildMessages', () => {
+  it('system grounds, design is fenced as data, task last', () => {
+    const msgs = buildMessages('Do the thing.', { text: 'Selected text: hi', truncated: false });
+    expect(msgs[0]).toEqual<ChatMessage>({ role: 'system', content: SYSTEM_PROMPT });
+    expect(msgs[1].role).toBe('user');
+    expect(msgs[1].content).toContain('---- design ----');
+    expect(msgs[1].content).toContain('Selected text: hi');
+    expect(msgs[1].content).toContain('---- end design ----');
+    expect(msgs[1].content).toContain('---- task ----\nDo the thing.');
+  });
+
+  it('omits the fence when there is no context', () => {
+    const msgs = buildMessages('Generate.', { text: '', truncated: false });
+    expect(msgs[1].content).not.toContain('---- design ----');
+    expect(msgs[1].content).toBe('---- task ----\nGenerate.');
+  });
+
+  it('prepends an honest truncation note when the context was cut', () => {
+    const msgs = buildMessages('Rewrite.', { text: 'partial', truncated: true });
+    expect(msgs[1].content).toContain('truncated to fit');
+    expect(msgs[1].content.indexOf('truncated to fit')).toBeLessThan(msgs[1].content.indexOf('---- design ----'));
+  });
+});
+
+describe('action catalog', () => {
+  it('exposes the five design actions in order', () => {
+    expect(Object.keys(DESIGN_ACTIONS)).toEqual(['generate', 'rewrite', 'translate', 'ideas', 'ask']);
+  });
+
+  it('lists are derived from the catalog (labels/flags never drift)', () => {
+    const list = designActionList();
+    expect(list.map((a) => a.id)).toEqual(Object.keys(DESIGN_ACTIONS));
+    expect(list.find((a) => a.id === 'rewrite')?.needsSelection).toBe(true);
+    expect(list.find((a) => a.id === 'translate')?.needsSelection).toBe(true);
+    expect(list.find((a) => a.id === 'generate')?.needsSelection).toBe(false);
+    expect(list.find((a) => a.id === 'generate')?.needsInstruction).toBe(true);
+    expect(list.find((a) => a.id === 'rewrite')?.needsInstruction).toBe(false);
+    expect(list[0].label).toBe(DESIGN_ACTIONS.generate.label);
+  });
+
+  it('narrows known ids and rejects unknown', () => {
+    expect(isDesignActionId('generate')).toBe(true);
+    expect(isDesignActionId('nope')).toBe(false);
+  });
+});
+
+describe('actionTask (prompt builders)', () => {
+  it('generate embeds the brief', () => {
+    const t = actionTask('generate', { instruction: 'Bold spring headline' });
+    expect(t).toContain('Bold spring headline');
+    expect(t).toContain('Return only the copy');
+  });
+
+  it('rewrite with no instruction uses the default improve prompt', () => {
+    const t = actionTask('rewrite', {});
+    expect(t).toContain('clearer, tighter, and more persuasive');
+    expect(t).toContain('Do NOT add any fact');
+  });
+
+  it('rewrite with an instruction embeds the tweak', () => {
+    expect(actionTask('rewrite', { instruction: 'make it playful' })).toContain('Rewrite it as follows: make it playful');
+  });
+
+  it('translate embeds the language and defaults to Spanish', () => {
+    expect(actionTask('translate', { language: 'French' })).toContain('into French');
+    expect(actionTask('translate', {})).toContain('into Spanish');
+  });
+
+  it('ideas clamps the count into [1,10] and defaults to 5', () => {
+    expect(actionTask('ideas', { instruction: 'coffee', count: 3 })).toContain('Suggest 3 distinct content ideas');
+    expect(actionTask('ideas', { instruction: 'coffee', count: 99 })).toContain('Suggest 10 distinct content ideas');
+    expect(actionTask('ideas', { instruction: 'coffee', count: 0 })).toContain('Suggest 5 distinct content ideas');
+    expect(actionTask('ideas', { instruction: 'coffee' })).toContain('Suggest 5 distinct content ideas');
+  });
+
+  it('ask embeds the question', () => {
+    expect(actionTask('ask', { instruction: 'What tone?' })).toContain('What tone?');
+  });
+
+  it('throws on an unknown id', () => {
+    expect(() => actionTask('bogus')).toThrow(/Unknown design action/);
+  });
+});
+
+describe('buildActionMessages (id + inputs + design -> messages)', () => {
+  it('resolves the task and fences the selection', () => {
+    const msgs = buildActionMessages('rewrite', { instruction: 'shorter' }, { selection: 'Buy now, save big' });
+    expect(msgs[0].content).toBe(SYSTEM_PROMPT);
+    expect(msgs[1].content).toContain('Selected text: Buy now, save big');
+    expect(msgs[1].content).toContain('Rewrite it as follows: shorter');
+  });
+
+  it('a from-scratch generate has no fence, only the task', () => {
+    const msgs = buildActionMessages('generate', { instruction: 'launch headline' }, {});
+    expect(msgs[1].content).not.toContain('---- design ----');
+    expect(msgs[1].content).toContain('launch headline');
+  });
+
+  it('honors the passed budget (truncation note appears)', () => {
+    const msgs = buildActionMessages('rewrite', {}, { selection: 'x'.repeat(500) }, 50);
+    expect(msgs[1].content).toContain('truncated to fit');
+  });
+
+  it('rejects an unknown id', () => {
+    expect(() => buildActionMessages('nope', {}, {})).toThrow(/Unknown design action/);
+  });
+});
+
+describe('parseCopy', () => {
+  it('returns clean text unchanged (idempotent)', () => {
+    expect(parseCopy('Spring is here.')).toBe('Spring is here.');
+    expect(parseCopy(parseCopy('Spring is here.'))).toBe('Spring is here.');
+  });
+
+  it('strips a wrapping markdown code fence', () => {
+    expect(parseCopy('```\nHeadline copy\n```')).toBe('Headline copy');
+    expect(parseCopy('```text\nHeadline copy\n```')).toBe('Headline copy');
+  });
+
+  it('strips matched surrounding quotes (straight and curly)', () => {
+    expect(parseCopy('"Big sale today"')).toBe('Big sale today');
+    expect(parseCopy('“Big sale today”')).toBe('Big sale today');
+  });
+
+  it('does not strip an internal or unmatched quote', () => {
+    expect(parseCopy('The "best" coffee')).toBe('The "best" coffee');
+    expect(parseCopy('"unterminated')).toBe('"unterminated');
+  });
+
+  it('trims surrounding whitespace', () => {
+    expect(parseCopy('   Hello   ')).toBe('Hello');
+  });
+});
+
+describe('parseIdeas', () => {
+  it('strips numbered and bulleted list markers', () => {
+    const out = parseIdeas('1. First idea\n2) Second idea\n- Third idea\n* Fourth\n• Fifth');
+    expect(out).toEqual(['First idea', 'Second idea', 'Third idea', 'Fourth', 'Fifth']);
+  });
+
+  it('drops blank lines and strips per-line wrapping quotes', () => {
+    expect(parseIdeas('\n1. "Quoted idea"\n\n2. Plain\n')).toEqual(['Quoted idea', 'Plain']);
+  });
+
+  it('falls back to non-empty lines when there is no list structure', () => {
+    expect(parseIdeas('Just one line')).toEqual(['Just one line']);
+    expect(parseIdeas('')).toEqual([]);
+  });
+});
@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import type { AiClient } from '@hanzo/ai';
+import { runChat, listModels } from '../src/hanzo';
+import type { ChatMessage } from '../src/design-core';
+
+// A fake AiClient capturing the params passed to chat.completions.create and
+// models.list. This is how we assert request shaping without a network.
+function fakeClient(reply: string, models: string[] = ['zen5', 'zen5-mini']): {
+  client: AiClient;
+  calls: { params: any; options: any }[];
+} {
+  const calls: { params: any; options: any }[] = [];
+  const client = {
+    chat: {
+      completions: {
+        create: async (params: any, options: any) => {
+          calls.push({ params, options });
+          return {
+            id: 'x',
+            object: 'chat.completion',
+            created: 0,
+            model: params.model,
+            choices: [{ index: 0, message: { role: 'assistant', content: reply }, finish_reason: 'stop' }],
+          };
+        },
+      },
+    },
+    models: {
+      list: async () => models.map((id) => ({ id, object: 'model' })),
+    },
+  } as unknown as AiClient;
+  return { client, calls };
+}
+
+const MESSAGES: ChatMessage[] = [
+  { role: 'system', content: 'sys' },
+  { role: 'user', content: 'hi' },
+];
+
+describe('runChat (request shaping over @hanzo/ai)', () => {
+  it('sends model + messages, stream:false, temperature, and returns the content', async () => {
+    const f = fakeClient('Generated copy.');
+    const out = await runChat(MESSAGES, { client: f.client, model: 'zen5-mini', temperature: 0.4 });
+    expect(out).toBe('Generated copy.');
+    expect(f.calls).toHaveLength(1);
+    expect(f.calls[0].params.model).toBe('zen5-mini');
+    expect(f.calls[0].params.stream).toBe(false);
+    expect(f.calls[0].params.temperature).toBe(0.4);
+    expect(f.calls[0].params.messages).toEqual(MESSAGES);
+  });
+
+  it('defaults the model to zen5 when none is given', async () => {
+    const f = fakeClient('x');
+    await runChat(MESSAGES, { client: f.client });
+    expect(f.calls[0].params.model).toBe('zen5');
+  });
+
+  it('throws when the model returns empty content', async () => {
+    const f = fakeClient('');
+    await expect(runChat(MESSAGES, { client: f.client })).rejects.toThrow(/no content/);
+  });
+
+  it('forwards the abort signal in options', async () => {
+    const f = fakeClient('x');
+    const controller = new AbortController();
+    await runChat(MESSAGES, { client: f.client, signal: controller.signal });
+    expect(f.calls[0].options.signal).toBe(controller.signal);
+  });
+});
+
+describe('listModels', () => {
+  it('returns the model ids from the client', async () => {
+    const f = fakeClient('x', ['zen5', 'zen5-mini', 'zen5-coder']);
+    expect(await listModels({ client: f.client })).toEqual(['zen5', 'zen5-mini', 'zen5-coder']);
+  });
+});
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
+}
@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    environment: 'node',
+  },
+});
@@ -0,0 +1,236 @@
+# Hanzo AI for Canvas LMS
+
+AI over your Canvas course — **summarize a course**, **draft assignment feedback**,
+**generate quiz/discussion questions**, **summarize student submissions**, and
+**draft an announcement**, plus a freeform "ask about the course" box. An
+embedded-app **panel** you host at `canvas.hanzo.ai`, backed by a small **OAuth +
+API-proxy service** that keeps the Canvas client secret and access tokens
+server-side.
+
+Built on the published Hanzo SDK:
+
+- **[`@hanzo/ai`](https://www.npmjs.com/package/@hanzo/ai)** — the headless client.
+  `createAiClient({ baseUrl, token }).chat.completions.create({ model, messages })`
+  and `.models.list()`. All model calls go to `https://api.hanzo.ai` on `/v1/...`
+  (never an `/api/` prefix). We import it; we do not reimplement the transport.
+- **[`@hanzo/iam`](https://www.npmjs.com/package/@hanzo/iam)** — Hanzo identity /
+  the `hk-…` API key the panel uses as its gateway bearer.
+
+Canvas is the dominant higher-ed / K12 LMS: courses, syllabi, modules, assignments,
+pages, discussions, and student submissions. This app reads those records through
+the Canvas REST API and grounds every AI draft in them. Everything it produces —
+feedback, questions, announcements, summaries — is a **draft for an educator to
+review**, not an authoritative grade or decision.
+
+> **Package name:** `@hanzo/canvas-lms` (directory `packages/canvas-lms`) — named to
+> avoid colliding with the design-tool package `packages/canva`.
+
+---
+
+## Architecture
+
+```
+Browser panel (dist/index.html, app.js)          Server service (dist/server.js)
+─────────────────────────────────────           ──────────────────────────────
+  reads Canvas via  ──►  /proxy/*  ──────────►   injects OAuth Bearer + refresh,
+  same-origin proxy      (cookie)                forwards to {canvas-host}/api/v1
+  (never sees a Canvas token)                    with the user's access token
+        │
+        └── calls api.hanzo.ai /v1 directly with the pasted hk-… Hanzo key
+            (@hanzo/ai headless client)
+```
+
+- The **panel** never holds a Canvas token or the client secret. It reaches Canvas
+  only through the same-origin `/proxy/*` endpoint (with an HttpOnly session
+  cookie). It talks to `api.hanzo.ai` directly with the user's pasted Hanzo key.
+- The **service** is the only place `CANVAS_CLIENT_SECRET` and the OAuth tokens
+  exist. It runs the install flow, holds the session, refreshes the token
+  transparently, and proxies REST calls.
+
+### Source layout (all pure logic is unit-tested)
+
+| File | Responsibility |
+| --- | --- |
+| `src/config.ts` | Canvas host normalization, REST version, gateway URL, server-secret config (`readServerConfig` fails fast). |
+| `src/canvas-oauth.ts` | OAuth2 Authorization-Code shaping: `authorizeUrl`, `tokenExchange`, `refreshExchange`, token parsing, non-rotating-refresh carry + expiry math. Pure. |
+| `src/canvas-api.ts` | REST v1 request wrappers (`listCourses`, `getCourse`, `listAssignments`, `listSubmissions`, `postSubmissionComment`, `createAnnouncement`, …) with pagination + `Link`-header parsing, and response parsers. Pure. |
+| `src/course.ts` | Course/assignment/submission/page/module JSON → windowed context text, HTML→text, honest truncation. Pure. |
+| `src/hanzo.ts` | Thin over `@hanzo/ai`: prompt assembly + the single `ask` path + `listModels`. |
+| `src/actions.ts` | The five AI actions (id → prompt) over `ask`. One code path to the model. |
+| `src/panel.ts` | Browser proxy-client request shaping + launch-context parsing. Pure. |
+| `src/app.ts` | The DOM glue for the panel (the one impure browser entry). |
+| `src/server.ts` | Node http service: OAuth install/callback + `/proxy/*`. |
+
+---
+
+## 1. Create a Canvas Developer Key
+
+Canvas OAuth apps authenticate with a **Developer Key** (an OAuth2
+client-id/secret). An account admin creates it in **Admin → Developer Keys → +
+Developer Key → API Key**:
+
+1. **Key Name**: `Hanzo AI for Canvas` (any label).
+2. **Redirect URIs** — exactly the URL your service serves the callback at:
+
+   ```
+   https://canvas.hanzo.ai/oauth/callback
+   ```
+
+   (For local development, add `http://localhost:8791/oauth/callback` too.)
+3. **Scopes** — leave **Enforce Scopes** *off* for the simplest setup (permissions
+   then follow the authorizing user's Canvas role). If you enable enforcement, add
+   the granular URL-scopes exported as `RECOMMENDED_SCOPES` in `src/config.ts`
+   (the read surface plus `PUT …/submissions/:user_id` and
+   `POST …/discussion_topics` for the two write-backs).
+4. **Save**, then **ON** the key's state, and copy the **Client ID** (the numeric
+   key id) and **Client Secret** (the "Key" / secret value).
+5. Note your institution's **Canvas host** (e.g. `school.instructure.com` or your
+   custom Canvas domain) — the app builds every OAuth + API URL from it.
+
+Because Canvas is self-hosted per institution, the host is a required deployment
+value (`CANVAS_HOST`); there is no fixed host list.
+
+---
+
+## 2. OAuth flow
+
+Standard **Authorization Code** grant (server-side secret):
+
+1. `GET /oauth/install` → 302 to
+   `https://{canvas-host}/login/oauth2/auth?client_id=…&response_type=code&redirect_uri=…&state=…`.
+2. The user consents; Canvas redirects back to `GET /oauth/callback?code=…&state=…`.
+3. The service verifies `state`, then POSTs to `/login/oauth2/token` with
+   `grant_type=authorization_code`, the `code`, the `client_id` + `client_secret`
+   (**in the body, server-side only**), and the same `redirect_uri`.
+4. It opens a session, sets an HttpOnly cookie, and the panel is authenticated.
+5. Access tokens are short-lived (~1h). The service refreshes with
+   `grant_type=refresh_token` **before** each proxied call when the token has
+   expired. Canvas does **not** rotate the refresh token (the refresh response omits
+   it), so the original refresh token is carried forward.
+
+> In-memory sessions here are for a single instance. For a multi-instance
+> deployment behind `hanzoai/ingress`, persist sessions + the OAuth `state` set to
+> `hanzoai/kv` (Valkey), and read `CANVAS_CLIENT_SECRET` from KMS (`kms.hanzo.ai`) —
+> never from a committed env file.
+
+---
+
+## 3. Canvas REST API
+
+All reads/writes go through `https://{canvas-host}/api/v1/...` with the user's
+`Authorization: Bearer {token}`. Canvas's own path is `/api/v1` — this is unrelated
+to the Hanzo gateway (which is always `api.hanzo.ai/v1/...`, never `/api/`).
+
+| Resource | Endpoint (relative to `/api/v1`) |
+| --- | --- |
+| Courses | `GET /courses`, `GET /courses/{id}?include[]=syllabus_body` |
+| Assignments | `GET /courses/{id}/assignments`, `GET /courses/{id}/assignments/{id}` |
+| Submissions | `GET /courses/{id}/assignments/{aid}/submissions`, `GET …/submissions/{user_id}` |
+| **Submission comment** (write) | `PUT /courses/{id}/assignments/{aid}/submissions/{user_id}` — body `{ "comment": { "text_comment": "…" } }` |
+| Discussions | `GET /courses/{id}/discussion_topics` |
+| **Announcement** (write) | `POST /courses/{id}/discussion_topics` — body `{ "title", "message", "is_announcement": true }` |
+| Pages | `GET /courses/{id}/pages`, `GET /courses/{id}/pages/{url_or_id}` |
+| Modules | `GET /courses/{id}/modules?include[]=items` |
+| Enrollments | `GET /courses/{id}/enrollments` |
+
+> Canvas models a submission comment as an **update to the submission** (a `PUT`
+> with `comment[text_comment]`), not a separate comments collection — there is no
+> `POST …/submissions/{id}/comments`. This app uses the correct `PUT` shape.
+
+List endpoints paginate with `page` (1-based) + `per_page` (max 100) and return the
+page relations in the **RFC 5988 `Link`** response header
+(`<…?page=2…>; rel="next"`), parsed by `parseLinkHeader` / `nextPage`.
+
+---
+
+## 4. The summarize-course / draft-feedback flow
+
+1. Connect the app (`/oauth/install`) so the service holds a Canvas token.
+2. Open the panel and **Load** a course (the picker lists the courses the connected
+   user can see). The panel pulls the course's syllabus, modules, assignments,
+   pages, and discussions through the proxy and assembles a windowed,
+   truncation-honest context (Canvas HTML is stripped to plain text).
+3. **Summarize course** — the model writes a course overview from the syllabus and
+   module structure, grounded only in the records.
+4. **Draft feedback** — pick an assignment and **Load submissions**; the model
+   drafts specific, constructive feedback for a student submission, grounded in what
+   the student actually wrote and the assignment's requirements. The result lands in
+   the Result box.
+5. Optional write-backs (gated, behind a confirm):
+   - **Post as submission comment** posts the Result back via
+     `PUT …/submissions/{user_id}` with `comment[text_comment]`, targeting the first
+     submitted student on the loaded assignment.
+   - **Post as announcement** posts the Result as a course announcement via
+     `POST …/discussion_topics` (`is_announcement: true`), first line as the subject.
+
+The other actions — **Generate questions** (quiz + discussion prompts from a
+page/module), **Summarize submissions** (submitted/missing/late, score spread,
+common strengths and problems), and **Draft announcement** — run the same way.
+
+---
+
+## Build & run
+
+```bash
+pnpm install
+pnpm --filter @hanzo/canvas-lms build      # → dist/ (panel + server)
+pnpm --filter @hanzo/canvas-lms test       # vitest
+pnpm --filter @hanzo/canvas-lms typecheck  # tsc --noEmit
+
+# run the service
+CANVAS_HOST=school.instructure.com   \
+CANVAS_CLIENT_ID=…   \
+CANVAS_CLIENT_SECRET=…   \
+CANVAS_REDIRECT_URI=https://canvas.hanzo.ai/oauth/callback   \
+node packages/canvas-lms/dist/server.js
+```
+
+### Required environment (service)
+
+| Var | Notes |
+| --- | --- |
+| `CANVAS_HOST` | Institution Canvas host, e.g. `school.instructure.com`. Normalized (scheme/path stripped). |
+| `CANVAS_CLIENT_ID` | Developer Key client id (public). |
+| `CANVAS_CLIENT_SECRET` | **Server only.** From KMS in production. |
+| `CANVAS_REDIRECT_URI` | Must match the key's registered redirect. |
+| `PORT` | Listen port (default `8791`). |
+
+`readServerConfig` throws on a missing value — the service refuses to start rather
+than pretend it can complete an OAuth exchange or reach an unknown Canvas host.
+
+---
+
+## Deploy over hanzoai/ingress
+
+Host the static panel (`dist/index.html`, `app.js`, `styles.css`) with the
+**hanzoai/static** plugin and run `dist/server.js` as a small service, both behind
+**hanzoai/ingress** at `canvas.hanzo.ai` (no nginx, no caddy):
+
+- `/` and the static assets → the panel.
+- `/oauth/*`, `/proxy/*`, `/healthz` → the service.
+
+Secrets come from **KMS** as `KMSSecret`-synced env; sessions from **Valkey**
+(`hanzoai/kv`) for multi-instance. Image published to
+`ghcr.io/hanzoai/canvas-lms:<tag>` by CI/CD (platform.hanzo.ai / Tekton) — never
+built locally.
+
+---
+
+## Alternative embed path: LTI 1.3
+
+This package ships the **OAuth2 + REST API** app (an external app the instructor
+connects, ideal for a standalone panel at `canvas.hanzo.ai`). Canvas also supports
+**LTI 1.3 / Advantage** as an in-Canvas launch: Canvas issues a signed OIDC launch
+JWT and the tool calls the same REST API (or LTI Advantage services — Names & Roles,
+Assignment & Grade Services). LTI is the better fit for a deep in-course placement
+(course navigation, assignment menu) and passes the course context (`custom_canvas_course_id`)
+in the launch — which `parseLaunchContext` already reads. The AI + context modules
+(`course.ts`, `hanzo.ts`, `actions.ts`, `canvas-api.ts`) are transport-agnostic and
+would be reused unchanged behind an LTI launch; only the auth front-door differs.
+This build ships the OAuth+API app.
+
+---
+
+*Routed through `api.hanzo.ai`. Answers are grounded in your Canvas course records —
+a draft for an educator to review, not an authoritative grade, decision, or the
+final word to a student.*
@@ -0,0 +1,86 @@
+// Build @hanzo/canvas-lms into dist/: bundle the web panel (app.ts) as ESM for the
+// browser, copy index.html (with its entry script stamped) + styles.css, and bundle
+// the OAuth + API-proxy server for Node. No framework — esbuild + Node stdlib only.
+// @hanzo/ai is bundled into both outputs (it is the headless client the panel and
+// server both call).
+//
+//   node build.js                                         → production build
+//   node build.js --watch                                 → rebuild on change
+//   HANZO_CANVAS_BASE=https://localhost:8443 node build.js → dev base (informational)
+//
+// Output layout:
+//   dist/index.html   dist/app.js   dist/styles.css   (panel)
+//   dist/server.js                                    (service)
+//
+// The panel is HOSTED over hanzoai/static behind hanzoai/ingress at canvas.hanzo.ai;
+// the server runs as a small service (OAuth callback + API proxy). All model calls go
+// to api.hanzo.ai regardless of the host base.
+
+import esbuild from 'esbuild';
+import { rmSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BASE = (process.env.HANZO_CANVAS_BASE || 'https://canvas.hanzo.ai').replace(/\/+$/, '');
+const watch = process.argv.includes('--watch');
+const src = join(__dirname, 'src');
+const dist = join(__dirname, 'dist');
+
+async function build() {
+  rmSync(dist, { recursive: true, force: true });
+  mkdirSync(dist, { recursive: true });
+
+  // Bundle the panel as ESM for the browser.
+  const panelCtx = await esbuild.context({
+    entryPoints: { app: join(src, 'app.ts') },
+    outdir: dist,
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    target: ['chrome90', 'edge90', 'firefox90', 'safari15'],
+    sourcemap: true,
+    minify: !watch,
+    logLevel: 'info',
+  });
+  await panelCtx.rebuild();
+
+  // Copy index.html (stamp __ENTRY__ + base) and styles.css.
+  const html = readFileSync(join(src, 'index.html'), 'utf8')
+    .split('__ENTRY__').join('app.js')
+    .replace('</head>', `  <meta name="hanzo:base" content="${BASE}" />\n</head>`);
+  writeFileSync(join(dist, 'index.html'), html);
+  copyFileSync(join(src, 'styles.css'), join(dist, 'styles.css'));
+
+  // Bundle the server as a Node ESM binary — our pure stdlib code + @hanzo/ai.
+  const serverCtx = await esbuild.context({
+    entryPoints: [join(src, 'server.ts')],
+    outfile: join(dist, 'server.js'),
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: ['node18'],
+    sourcemap: true,
+    minify: !watch,
+    banner: { js: "import { createRequire as __cr } from 'module'; const require = __cr(import.meta.url);" },
+    logLevel: 'info',
+  });
+  await serverCtx.rebuild();
+
+  console.log(`Hanzo AI for Canvas built -> dist/  (base ${BASE})`);
+  console.log('   Panel: dist/index.html  ·  Service: dist/server.js');
+
+  if (watch) {
+    await panelCtx.watch();
+    await serverCtx.watch();
+    console.log('watching...');
+  } else {
+    await panelCtx.dispose();
+    await serverCtx.dispose();
+  }
+}
+
+build().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
@@ -0,0 +1,51 @@
+{
+  "name": "@hanzo/canvas-lms",
+  "version": "1.0.0",
+  "description": "Hanzo AI for Canvas LMS — AI over your course: summarize a course, draft assignment feedback, generate quiz/discussion questions, summarize student submissions, and draft an announcement. An embedded-app panel plus an OAuth + API-proxy service, built on @hanzo/ai and @hanzo/iam over the api.hanzo.ai gateway.",
+  "type": "module",
+  "scripts": {
+    "build": "node build.js",
+    "watch": "node build.js --watch",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hanzo/ai": "^0.2.0",
+    "@hanzo/iam": "^0.13.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "esbuild": "^0.25.8",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "hanzo",
+    "canvas",
+    "lms",
+    "education",
+    "instructure",
+    "ai",
+    "oauth"
+  ],
+  "author": "Hanzo AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hanzoai/extension.git",
+    "directory": "packages/canvas-lms"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "main": "dist/server.js"
+}
@@ -0,0 +1,109 @@
+// The AI actions over a Canvas course — summarize the course, draft assignment
+// feedback, generate quiz/discussion questions, summarize student submissions, and
+// draft an announcement. Each is a prompt template applied to the windowed course
+// context via the single `ask` primitive in hanzo.ts. There is exactly ONE code path
+// to the model: an action is (id → prompt), and the panel and any server-side caller
+// resolve an id here and call `ask`. No action speaks to the gateway directly. (A
+// freeform "ask about the course" is `ask` directly, not an action — it has no fixed
+// prompt.)
+
+import { ask, type AskOptions, type CourseMeta } from './hanzo.js';
+import type { CourseContext } from './course.js';
+
+// The action catalog. `id` is the stable key the panel's chips use; `label` is the
+// button text; `prompt` is the instruction handed to the model as the task, over the
+// fenced course records. Prompts are specific and output-shaped (bullets, structured
+// lists) so results are consistent and parseable.
+export const ACTIONS = {
+  summarizeCourse: {
+    label: 'Summarize course',
+    prompt:
+      'Write a clear overview of this course for a student or a colleague, grounded ' +
+      'in the syllabus and module structure in these records. Cover: what the course ' +
+      'is about, how it is organised (the modules and their sequence), the major ' +
+      'assignments and how grading works if the records say, and any key policies. ' +
+      'Use a short headline followed by grouped bullets. Base every statement on the ' +
+      'records; if the syllabus or modules look incomplete, say so plainly.',
+  },
+  draftFeedback: {
+    label: 'Draft feedback',
+    prompt:
+      'Draft constructive, specific feedback for the student submission in these ' +
+      'records, addressed to the student. Ground every point in what the submission ' +
+      'actually contains and in the assignment’s stated requirements; do not invent ' +
+      'content the student did not write or a grade the records do not show. Lead with ' +
+      'what was done well, then give concrete, actionable suggestions for improvement, ' +
+      'and close with an encouraging next step. Keep the tone supportive and ' +
+      'professional. Return only the feedback text, ready to paste as a submission ' +
+      'comment for the instructor to review.',
+  },
+  generateQuestions: {
+    label: 'Generate questions',
+    prompt:
+      'From the course content in these records (a page, module, or assignment), ' +
+      'generate assessment questions. Produce two groups. First, "Quiz questions": 5 ' +
+      'to 8 questions that check understanding of the material, a mix of ' +
+      'multiple-choice (with options and the correct answer marked) and short-answer, ' +
+      'each tied to a specific idea in the records. Second, "Discussion prompts": 3 ' +
+      'open-ended prompts that invite analysis or application. Base every question ' +
+      'strictly on the provided content; do not test material that is not present.',
+  },
+  summarizeSubmissions: {
+    label: 'Summarize submissions',
+    prompt:
+      'Summarize the student submissions in these records for the instructor. Cover: ' +
+      'how many submitted vs are missing or late, the range of scores or grades if the ' +
+      'records show them, common strengths and common problems across the responses, ' +
+      'and any submissions that stand out (exemplary or struggling) — referenced by ' +
+      'user id, not invented names. Structure as a one-line headline followed by ' +
+      'grouped bullets. Do not fabricate scores or content the records do not contain.',
+  },
+  draftAnnouncement: {
+    label: 'Draft announcement',
+    prompt:
+      'Draft a course announcement for the students, grounded in these course records ' +
+      '(upcoming assignments, due dates, module content). Write a short, clear ' +
+      'announcement with a specific subject line on the first line, then the body: what ' +
+      'is happening, what students need to do, and any relevant due date drawn from the ' +
+      'records. Keep it warm and concise. Do not invent dates or requirements that are ' +
+      'not in the records. Return the subject line and body, ready for the instructor ' +
+      'to review and post.',
+  },
+} as const;
+
+// An action id from the catalog.
+export type ActionId = keyof typeof ACTIONS;
+
+// isActionId narrows an arbitrary string to a known action id. Boundary guard — the
+// panel and the server validate an inbound id here before running it.
+export function isActionId(id: string): id is ActionId {
+  return Object.prototype.hasOwnProperty.call(ACTIONS, id);
+}
+
+// actionPrompt resolves an action id to its prompt template. Throws on an unknown id
+// (a boundary error, surfaced to the caller) rather than silently running a default.
+// Pure.
+export function actionPrompt(id: string): string {
+  if (!isActionId(id)) throw new Error(`Unknown action: ${id}`);
+  return ACTIONS[id].prompt;
+}
+
+// actionList is the ordered catalog for building the UI (chips) — id + label,
+// derived from ACTIONS so the panel and the catalog can never drift. Pure.
+export function actionList(): Array<{ id: ActionId; label: string }> {
+  return (Object.keys(ACTIONS) as ActionId[]).map((id) => ({ id, label: ACTIONS[id].label }));
+}
+
+// runAction is the single entry point every surface calls: resolve the action's
+// prompt and run it over the windowed course context via `ask`. This is the one code
+// path from an action id to the model. Async so an unknown id surfaces as a rejected
+// promise (not a synchronous throw), giving callers ONE way to handle failure:
+// `await`/`.catch`. A gateway error rejects via `ask`.
+export async function runAction(
+  id: string,
+  ctx: CourseContext,
+  meta?: CourseMeta,
+  opts: AskOptions = {},
+): Promise<string> {
+  return ask(actionPrompt(id), ctx, meta, opts);
+}
@@ -0,0 +1,375 @@
+// The Canvas panel glue: the embedded/linked-app page that opens with a course in
+// context and drives the AI actions over the course's live records. All the
+// logic-heavy work (action prompts, context windowing, chat shaping, proxy request
+// shaping, auth) lives in its own tested modules; this file binds them to the DOM. It
+// is the one impure, browser-only entry point.
+//
+// Data flow: the panel reads Canvas ONLY through the same-origin server proxy
+// (createProxyClient), which holds the OAuth token server-side. It pulls the course's
+// syllabus / modules / assignments / pages / discussions, assembles a windowed context
+// (buildCourseContext), and runs an action or a freeform question against api.hanzo.ai
+// with the pasted Hanzo key. The optional write-backs (submission comment, course
+// announcement) post back through the same proxy, behind explicit buttons.
+
+import { actionList, isActionId, runAction } from './actions.js';
+import { ask as askHanzo, listModels, type CourseMeta } from './hanzo.js';
+import {
+  buildCourseContext,
+  contextNote,
+  courseSection,
+  moduleSection,
+  assignmentSection,
+  pageSection,
+  discussionSection,
+  submissionSection,
+  type CourseContext,
+  type Section,
+} from './course.js';
+import { DEFAULT_MODEL } from './config.js';
+import { getApiKey, setApiKey, hasApiKey, bearer, validateKey } from './auth.js';
+import { createProxyClient, parseLaunchContext, type ProxyClient } from './panel.js';
+import type { Course, Assignment, Submission } from './canvas-api.js';
+
+const $ = <T extends HTMLElement = HTMLElement>(id: string) => document.getElementById(id) as T;
+
+let controller: AbortController | null = null;
+
+window.addEventListener('DOMContentLoaded', () => {
+  const launch = parseLaunchContext(window.location.search);
+
+  const courseEl = $<HTMLSelectElement>('course');
+  const assignmentEl = $<HTMLSelectElement>('assignment');
+  const loadBtn = $<HTMLButtonElement>('load');
+  const loadSubsBtn = $<HTMLButtonElement>('loadsubs');
+  const recordsEl = $('records');
+  const outputEl = $<HTMLTextAreaElement>('output');
+  const statusEl = $('status');
+  const modelEl = $<HTMLSelectElement>('model');
+  const chipRow = $('chips');
+  const runBtn = $<HTMLButtonElement>('run');
+  const stopBtn = $<HTMLButtonElement>('stop');
+  const promptEl = $<HTMLTextAreaElement>('prompt');
+  const apiKeyEl = $<HTMLInputElement>('apikey');
+  const saveKeyBtn = $<HTMLButtonElement>('savekey');
+  const authHint = $('authhint');
+  const commentBtn = $<HTMLButtonElement>('comment');
+  const announceBtn = $<HTMLButtonElement>('announce');
+
+  apiKeyEl.value = getApiKey();
+  reflectAuth();
+  void populateModels();
+  void populateCourses();
+
+  const client: ProxyClient = createProxyClient();
+
+  // Loaded state: the course-overview sections, the loaded submissions (a separate
+  // section appended on demand), and the ids the write-backs target.
+  let overview: Section[] = [];
+  let submissions: Submission[] = [];
+  let ctx: CourseContext | null = null;
+  let meta: CourseMeta = {};
+  let currentCourseId = '';
+  let currentAssignmentId = '';
+  let assignments: Assignment[] = [];
+
+  // Action chips — derived from the catalog so UI and logic never drift.
+  for (const a of actionList()) {
+    const b = document.createElement('button');
+    b.className = 'chip';
+    b.textContent = a.label;
+    b.dataset.action = a.id;
+    b.onclick = () => void run(a.id);
+    chipRow.appendChild(b);
+  }
+
+  loadBtn.onclick = () => void loadCourse();
+  loadSubsBtn.onclick = () => void loadSubmissions();
+  courseEl.onchange = () => {
+    currentCourseId = courseEl.value;
+  };
+  assignmentEl.onchange = () => {
+    currentAssignmentId = assignmentEl.value;
+  };
+  runBtn.onclick = () => {
+    const prompt = promptEl.value.trim();
+    if (prompt) void ask(prompt);
+  };
+  stopBtn.onclick = () => controller?.abort();
+  commentBtn.onclick = () => void postComment();
+  announceBtn.onclick = () => void postAnnouncement();
+  saveKeyBtn.onclick = async () => {
+    const key = apiKeyEl.value.trim();
+    setStatus('Checking key…');
+    try {
+      const models = await validateKey(key);
+      setApiKey(key);
+      fillModels(models);
+      reflectAuth();
+      setStatus('Key saved.', 'ok');
+    } catch (e: any) {
+      setStatus(e?.message || 'Key rejected.', 'error');
+    }
+  };
+
+  // If we launched already scoped to a course, load it straight away.
+  if (launch.courseId) {
+    void populateCourses().then(() => {
+      courseEl.value = launch.courseId;
+      currentCourseId = launch.courseId;
+      void loadCourse();
+    });
+  }
+
+  // populateCourses fills the course picker from the proxy. An auth failure leaves the
+  // picker empty with a status hint pointing at the connect flow.
+  async function populateCourses(): Promise<void> {
+    setStatus('Loading courses…');
+    try {
+      const { items } = await client.listCourses({ perPage: 100 });
+      fillCourses(items);
+      setStatus(
+        items.length ? `Loaded ${items.length} courses.` : 'No courses visible.',
+        items.length ? 'ok' : 'warn',
+      );
+    } catch (e: any) {
+      setStatus(
+        e?.message || 'Could not load courses — is the app connected? (Connect on canvas.hanzo.ai)',
+        'error',
+      );
+    }
+  }
+
+  // loadCourse pulls the scoped course's records and assembles the overview context
+  // the actions run over. The course/syllabus, modules, assignments, pages, and
+  // discussions are fetched in parallel; each failure is tolerated so a course missing
+  // one area still yields a usable context.
+  async function loadCourse(): Promise<void> {
+    const courseId = courseEl.value || currentCourseId;
+    if (!courseId) {
+      setStatus('Pick a course first.', 'warn');
+      return;
+    }
+    currentCourseId = courseId;
+    setStatus('Loading course records…');
+    const [course, modules, assigns, pages, discussions] = await Promise.all([
+      client.getCourse(courseId).catch(() => null),
+      client.listModules(courseId, { perPage: 100 }).then((r) => r.items).catch(() => []),
+      client.listAssignments(courseId, { perPage: 100 }).then((r) => r.items).catch(() => [] as Assignment[]),
+      client.listPages(courseId, { perPage: 100 }).then((r) => r.items).catch(() => []),
+      client.listDiscussions(courseId, { perPage: 100 }).then((r) => r.items).catch(() => []),
+    ]);
+
+    assignments = assigns;
+    submissions = [];
+    fillAssignments(assigns);
+
+    overview = [
+      ...(course ? [courseSection(course)] : []),
+      moduleSection(modules),
+      assignmentSection(assigns),
+      pageSection(pages),
+      discussionSection(discussions),
+    ];
+    meta = course ? courseMetaOf(course) : {};
+    rebuildContext();
+
+    recordsEl.textContent =
+      `${modules.length} modules · ${assigns.length} assignments · ${pages.length} pages · ${discussions.length} discussions`;
+    announceBtn.disabled = false;
+    announceBtn.title = 'Post the result as a course announcement';
+    loadSubsBtn.disabled = assigns.length === 0;
+    setStatus(contextNote(ctx!));
+  }
+
+  // loadSubmissions pulls the selected assignment's submissions and appends them to the
+  // context so the feedback / summarize-submissions actions have student work. Enables
+  // the submission-comment write-back against the first submission.
+  async function loadSubmissions(): Promise<void> {
+    const assignmentId = assignmentEl.value || currentAssignmentId;
+    if (!currentCourseId || !assignmentId) {
+      setStatus('Load a course and pick an assignment first.', 'warn');
+      return;
+    }
+    currentAssignmentId = assignmentId;
+    setBusy(true);
+    setStatus('Loading submissions…');
+    try {
+      const { items } = await client.listSubmissions(currentCourseId, assignmentId, { perPage: 100 });
+      submissions = items;
+      rebuildContext();
+      const withWork = submissions.filter((s) => s.workflowState && s.workflowState !== 'unsubmitted');
+      commentBtn.disabled = withWork.length === 0;
+      commentBtn.title = withWork.length
+        ? `Post the result as a comment on user ${withWork[0].userId}'s submission`
+        : 'No submitted work to comment on';
+      recordsEl.textContent += ` · ${submissions.length} submissions`;
+      setStatus(contextNote(ctx!));
+    } catch (e: any) {
+      setStatus(e?.message || 'Could not load submissions.', 'error');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // rebuildContext re-windows the overview + any loaded submissions into one context.
+  function rebuildContext(): void {
+    ctx = buildCourseContext([...overview, ...(submissions.length ? [submissionSection(submissions)] : [])]);
+  }
+
+  // run executes one of the named actions over the loaded course context.
+  async function run(actionId: string): Promise<void> {
+    if (!isActionId(actionId)) return;
+    await execute((c, m, opts) => runAction(actionId, c, m, opts));
+  }
+
+  // ask executes a freeform question over the loaded course context.
+  async function ask(prompt: string): Promise<void> {
+    await execute((c, m, opts) => askHanzo(prompt, c, m, opts));
+  }
+
+  // execute is the shared runner: require a loaded context, call the model, show the
+  // result. Both the chips and freeform ask funnel through here (one path).
+  async function execute(
+    call: (
+      c: CourseContext,
+      m: CourseMeta,
+      opts: { token: string; model: string; signal: AbortSignal },
+    ) => Promise<string>,
+  ): Promise<void> {
+    if (!ctx || ctx.totalBlocks === 0) {
+      setStatus('Load a course first (pick one and press Load).', 'warn');
+      return;
+    }
+    controller?.abort();
+    controller = new AbortController();
+    setBusy(true);
+    setStatus(contextNote(ctx));
+    outputEl.value = '';
+    try {
+      const text = await call(ctx, meta, {
+        token: bearer(),
+        model: modelEl.value || DEFAULT_MODEL,
+        signal: controller.signal,
+      });
+      outputEl.value = text;
+      setStatus('Done.', 'ok');
+    } catch (e: any) {
+      if (e?.name === 'AbortError') setStatus('Stopped.');
+      else setStatus(e?.message || 'Request failed.', 'error');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // postComment writes the current output back to Canvas as a comment on the first
+  // submitted student's submission — an explicit, documented write-back. Guarded: it
+  // never posts an empty body and always confirms who it targeted.
+  async function postComment(): Promise<void> {
+    const body = outputEl.value.trim();
+    const target = submissions.find((s) => s.workflowState && s.workflowState !== 'unsubmitted');
+    if (!target) return setStatus('No submitted work to comment on.', 'warn');
+    if (!body) return setStatus('Nothing to post — run an action or write feedback first.', 'warn');
+    if (!confirm(`Post this as a comment on user ${target.userId}'s submission?`)) return;
+    setBusy(true);
+    setStatus('Posting comment to Canvas…');
+    try {
+      await client.postSubmissionComment(currentCourseId, currentAssignmentId, target.userId, body);
+      setStatus(`Comment posted on user ${target.userId}'s submission.`, 'ok');
+    } catch (e: any) {
+      setStatus(e?.message || 'Comment failed.', 'error');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // postAnnouncement writes the current output back as a course announcement. Canvas
+  // needs a title + body; we take the first line of the result as the title and the
+  // rest as the body, so a "subject line then body" draft posts cleanly.
+  async function postAnnouncement(): Promise<void> {
+    const text = outputEl.value.trim();
+    if (!currentCourseId) return setStatus('Load a course first.', 'warn');
+    if (!text) return setStatus('Nothing to post — draft an announcement first.', 'warn');
+    const nl = text.indexOf('\n');
+    const title = (nl === -1 ? text : text.slice(0, nl)).trim().slice(0, 200);
+    const message = (nl === -1 ? text : text.slice(nl + 1)).trim() || text;
+    if (!confirm(`Post a course announcement titled “${title}”?`)) return;
+    setBusy(true);
+    setStatus('Posting announcement to Canvas…');
+    try {
+      await client.createAnnouncement(currentCourseId, title, message);
+      setStatus('Announcement posted.', 'ok');
+    } catch (e: any) {
+      setStatus(e?.message || 'Announcement failed.', 'error');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // ---- small DOM helpers ----------------------------------------------------
+
+  let courses: Course[] = [];
+  function courseMetaOf(course: Course): CourseMeta {
+    return { name: course.name || undefined, courseCode: course.courseCode || undefined, term: course.termName || undefined };
+  }
+  function fillCourses(items: Course[]): void {
+    courses = items;
+    courseEl.innerHTML = '';
+    for (const c of items) {
+      const opt = document.createElement('option');
+      opt.value = String(c.id);
+      opt.textContent = c.name || c.courseCode || `Course ${c.id}`;
+      courseEl.appendChild(opt);
+    }
+    if (items.length && !currentCourseId) currentCourseId = String(items[0].id);
+  }
+  function fillAssignments(items: Assignment[]): void {
+    assignmentEl.innerHTML = '';
+    for (const a of items) {
+      const opt = document.createElement('option');
+      opt.value = String(a.id);
+      opt.textContent = a.name || `Assignment ${a.id}`;
+      assignmentEl.appendChild(opt);
+    }
+    currentAssignmentId = items.length ? String(items[0].id) : '';
+  }
+
+  async function populateModels(): Promise<void> {
+    try {
+      fillModels(await listModels({ token: bearer() }));
+    } catch {
+      fillModels([DEFAULT_MODEL]);
+    }
+  }
+  function fillModels(ids: string[]): void {
+    const list = ids.length ? ids : [DEFAULT_MODEL];
+    modelEl.innerHTML = '';
+    for (const id of list) {
+      const opt = document.createElement('option');
+      opt.value = id;
+      opt.textContent = id;
+      modelEl.appendChild(opt);
+    }
+    if (list.includes(DEFAULT_MODEL)) modelEl.value = DEFAULT_MODEL;
+  }
+
+  function reflectAuth(): void {
+    authHint.textContent = hasApiKey()
+      ? 'Using your saved Hanzo key.'
+      : 'No key saved — using public models. Paste an hk-… key for your org models.';
+  }
+
+  function setBusy(b: boolean): void {
+    runBtn.disabled = b;
+    stopBtn.disabled = !b;
+    loadBtn.disabled = b;
+    loadSubsBtn.disabled = b || assignments.length === 0;
+    for (const c of Array.from(chipRow.querySelectorAll('button'))) (c as HTMLButtonElement).disabled = b;
+    announceBtn.disabled = b || !currentCourseId;
+    commentBtn.disabled = b || submissions.length === 0;
+  }
+
+  function setStatus(msg: string, kind: '' | 'ok' | 'warn' | 'error' = ''): void {
+    statusEl.textContent = msg;
+    statusEl.className = `status${kind ? ' ' + kind : ''}`;
+  }
+});
@@ -0,0 +1,55 @@
+// Auth for the web panel: the zero-setup pasted-key path for the Hanzo gateway. The
+// Canvas panel is a static web page (iframe), so the Hanzo credential lives in
+// localStorage and is validated by a real /v1/models call — a key that can't list
+// models is rejected before it's saved, so the user learns at paste time, not at
+// first action. Mirrors @hanzo/procore exactly (one way to hold a key).
+//
+// The Canvas access token (for reading courses/assignments/submissions) is a SEPARATE
+// credential minted server-side by the OAuth flow and held by server.ts; the panel
+// reaches Canvas only through the server proxy (with its session cookie), so it never
+// holds the Canvas token or secret. This module is only the Hanzo-gateway bearer.
+
+import { APIKEY_STORAGE_KEY, pickBearer } from './config.js';
+import { listModels } from './hanzo.js';
+
+export function getApiKey(): string {
+  try {
+    return localStorage.getItem(APIKEY_STORAGE_KEY) || '';
+  } catch {
+    return '';
+  }
+}
+
+export function setApiKey(key: string): void {
+  try {
+    const k = key.trim();
+    if (k) localStorage.setItem(APIKEY_STORAGE_KEY, k);
+    else localStorage.removeItem(APIKEY_STORAGE_KEY);
+  } catch {
+    /* private-mode / storage disabled — the in-memory key still works this session */
+  }
+}
+
+export function clearApiKey(): void {
+  setApiKey('');
+}
+
+export function hasApiKey(): boolean {
+  return !!getApiKey();
+}
+
+// bearer is the credential the chat call sends: the pasted key (or empty for
+// anonymous public models). When Hanzo OAuth lands it slots in as the second argument
+// to pickBearer with no change to callers.
+export function bearer(): string {
+  return pickBearer(getApiKey(), '');
+}
+
+// validateKey confirms a pasted key actually works by listing models with it. Returns
+// the models on success so the caller populates the picker in one round-trip; throws
+// with the gateway's message on failure.
+export async function validateKey(key: string): Promise<string[]> {
+  const k = key.trim();
+  if (!k) throw new Error('Enter a Hanzo API key (hk-…).');
+  return listModels({ token: k });
+}
@@ -0,0 +1,582 @@
+// Canvas REST API v1 — pure request shaping + response parsing. Every function
+// returns a PreparedRequest (url + headers [+ body]) or parses a response body;
+// none opens a socket, so the whole API surface is unit-testable without a
+// network. server.ts is the thin glue that fetches these shapes with the OAuth
+// Bearer access token.
+//
+// The REST root is `https://{host}/api/v1` (see config.apiBaseUrl). Canvas scopes
+// reads/writes by the authorizing user's Bearer token; course-scoped resources
+// take the course id in the path (…/courses/{id}/…). Docs:
+// canvas.instructure.com/doc/api/courses.html, assignments.html, submissions.html,
+// discussion_topics.html, pages.html, modules.html, enrollments.html.
+
+// A prepared GET: url + headers a single fetch needs (Bearer only).
+export interface PreparedGet {
+  url: string;
+  headers: Record<string, string>;
+}
+
+// A prepared write (POST/PUT): adds the JSON body and Content-Type. Canvas accepts
+// a JSON body (Content-Type: application/json) for these endpoints; we use it so
+// nested params stay structured rather than form-bracket-encoded.
+export interface PreparedWrite extends PreparedGet {
+  method: 'POST' | 'PUT';
+  body: string;
+}
+
+// headers builds the auth header set common to every request.
+function headers(accessToken: string): Record<string, string> {
+  return { Authorization: `Bearer ${accessToken}` };
+}
+
+// jsonHeaders adds Content-Type for a write body on top of the auth header.
+function jsonHeaders(accessToken: string): Record<string, string> {
+  return { ...headers(accessToken), 'Content-Type': 'application/json' };
+}
+
+// The scope every request carries: which REST root and which bearer. Grouping them
+// keeps every wrapper's signature small.
+export interface Scope {
+  apiBase: string;
+  accessToken: string;
+}
+
+// Pagination controls. Canvas paginates with page (1-based) + per_page and returns
+// the page relations (next/prev/first/last) in the RFC 5988 `Link` response header
+// (parsed by the caller with parseLinkHeader). We attach these as query params on
+// list endpoints.
+export interface Page {
+  page?: number;
+  perPage?: number;
+}
+
+// DEFAULT_PER_PAGE is Canvas's documented maximum page size; 100 minimises
+// round-trips (Canvas's own default is only 10).
+export const DEFAULT_PER_PAGE = 100;
+
+// pageParams renders pagination into query pairs, clamping per_page to the
+// documented maximum. Only emits params that are set, so an unpaginated call stays
+// clean. Pure — unit-tested.
+export function pageParams(page: Page | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!page) return out;
+  if (typeof page.page === 'number' && page.page > 0) out.page = String(Math.floor(page.page));
+  if (typeof page.perPage === 'number' && page.perPage > 0) {
+    out.per_page = String(Math.min(Math.floor(page.perPage), DEFAULT_PER_PAGE));
+  }
+  return out;
+}
+
+// A repeated query param, e.g. Canvas's `include[]=syllabus_body`. buildUrl expands
+// an array value into one pair per element with a trailing `[]` on the key.
+type Query = Record<string, string | string[] | undefined>;
+
+// buildUrl joins the REST root + path and appends a query string, dropping
+// undefined/empty values and expanding arrays into Canvas's `key[]=v` repetition.
+// One place builds every URL so scoping/pagination params are applied
+// consistently. Pure.
+function buildUrl(apiBase: string, path: string, query: Query = {}): string {
+  const base = `${apiBase.replace(/\/+$/, '')}${path}`;
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (Array.isArray(v)) {
+      for (const item of v) if (item !== undefined && item !== '') q.append(`${k}[]`, item);
+    } else if (v !== undefined && v !== '') {
+      q.set(k, v);
+    }
+  }
+  const qs = q.toString();
+  return qs ? `${base}?${qs}` : base;
+}
+
+// enc encodes a single path segment (ids are integers and page urls are slugs, but
+// we encode defensively so a stray value can never break — or traverse — the path).
+function enc(segment: number | string): string {
+  return encodeURIComponent(String(segment));
+}
+
+// ---- Courses --------------------------------------------------------------
+
+// listCourses — the courses the authorizing user can see. Bearer scope only (no
+// course in the path). The panel's picker uses this to choose which course to run
+// against.
+export function listCourses(scope: Scope, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, '/courses', pageParams(page)),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// getCourse — one course. `includes` maps to Canvas `include[]` associations; we
+// default to `syllabus_body` (an HTML syllabus) since the summarize-course action
+// grounds on it. Pass `[]` to fetch the bare course.
+export function getCourse(
+  scope: Scope,
+  courseId: number | string,
+  includes: readonly string[] = ['syllabus_body'],
+): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}`, {
+      include: includes.length ? [...includes] : undefined,
+    }),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// ---- Assignments ----------------------------------------------------------
+
+// listAssignments — the assignments in a course. Course-scoped path.
+export function listAssignments(scope: Scope, courseId: number | string, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/assignments`, pageParams(page)),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// getAssignment — one assignment in full (description, due date, points, submission
+// types). This is what the feedback/question actions read.
+export function getAssignment(
+  scope: Scope,
+  courseId: number | string,
+  assignmentId: number | string,
+): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/assignments/${enc(assignmentId)}`),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// ---- Submissions ----------------------------------------------------------
+
+// listSubmissions — the submissions for an assignment. Course + assignment scoped
+// path; `include[]=submission_comments` so existing comments come along for the
+// summarize/feedback context.
+export function listSubmissions(
+  scope: Scope,
+  courseId: number | string,
+  assignmentId: number | string,
+  page?: Page,
+): PreparedGet {
+  return {
+    url: buildUrl(
+      scope.apiBase,
+      `/courses/${enc(courseId)}/assignments/${enc(assignmentId)}/submissions`,
+      { include: ['submission_comments'], ...pageParams(page) },
+    ),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// getSubmission — one student's submission (by user id) with its comment thread.
+export function getSubmission(
+  scope: Scope,
+  courseId: number | string,
+  assignmentId: number | string,
+  userId: number | string,
+): PreparedGet {
+  return {
+    url: buildUrl(
+      scope.apiBase,
+      `/courses/${enc(courseId)}/assignments/${enc(assignmentId)}/submissions/${enc(userId)}`,
+      { include: ['submission_comments'] },
+    ),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// postSubmissionComment — add a text comment to a student's submission. Canvas
+// models a submission comment as an UPDATE to the submission (PUT
+// …/submissions/{user_id} with a `comment[text_comment]`), not a separate comments
+// collection — this is the ONE feedback write path, behind an explicit action.
+// Returns a PreparedWrite (PUT + JSON body).
+export function postSubmissionComment(
+  scope: Scope,
+  courseId: number | string,
+  assignmentId: number | string,
+  userId: number | string,
+  text: string,
+): PreparedWrite {
+  return {
+    method: 'PUT',
+    url: buildUrl(
+      scope.apiBase,
+      `/courses/${enc(courseId)}/assignments/${enc(assignmentId)}/submissions/${enc(userId)}`,
+    ),
+    headers: jsonHeaders(scope.accessToken),
+    body: JSON.stringify({ comment: { text_comment: text } }),
+  };
+}
+
+// ---- Discussions ----------------------------------------------------------
+
+// listDiscussions — the discussion topics in a course (announcements included when
+// they are discussion-backed). Course-scoped path.
+export function listDiscussions(scope: Scope, courseId: number | string, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/discussion_topics`, pageParams(page)),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// createAnnouncement — post a course announcement. In Canvas an announcement is a
+// discussion topic with `is_announcement: true` (POST …/discussion_topics) — the
+// second gated write path. Returns a PreparedWrite (POST + JSON body).
+export function createAnnouncement(
+  scope: Scope,
+  courseId: number | string,
+  title: string,
+  message: string,
+): PreparedWrite {
+  return {
+    method: 'POST',
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/discussion_topics`),
+    headers: jsonHeaders(scope.accessToken),
+    body: JSON.stringify({ title, message, is_announcement: true }),
+  };
+}
+
+// ---- Pages ----------------------------------------------------------------
+
+// listPages — the wiki pages in a course. Course-scoped path.
+export function listPages(scope: Scope, courseId: number | string, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/pages`, pageParams(page)),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// getPage — one wiki page in full (its HTML body). Canvas addresses a page by its
+// url slug or page id.
+export function getPage(
+  scope: Scope,
+  courseId: number | string,
+  urlOrId: number | string,
+): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/pages/${enc(urlOrId)}`),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// ---- Modules --------------------------------------------------------------
+
+// listModules — the modules in a course, with their items inlined
+// (`include[]=items`) so the course-overview context sees the module structure.
+export function listModules(scope: Scope, courseId: number | string, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/modules`, {
+      include: ['items'],
+      ...pageParams(page),
+    }),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// ---- Enrollments ----------------------------------------------------------
+
+// listEnrollments — the enrollments in a course (who is a student / teacher / TA).
+export function listEnrollments(scope: Scope, courseId: number | string, page?: Page): PreparedGet {
+  return {
+    url: buildUrl(scope.apiBase, `/courses/${enc(courseId)}/enrollments`, pageParams(page)),
+    headers: headers(scope.accessToken),
+  };
+}
+
+// ---- Pagination header (RFC 5988 Link) ------------------------------------
+
+// The page relations Canvas returns in the `Link` header — each an absolute URL.
+export interface CanvasLinks {
+  current?: string;
+  next?: string;
+  prev?: string;
+  first?: string;
+  last?: string;
+}
+
+// parseLinkHeader reads Canvas's RFC 5988 `Link` header into the page relations.
+// Canvas returns entries like `<https://host/api/v1/courses?page=2&per_page=100>;
+// rel="next"`. Accepts a Headers instance or a plain header map so it works against
+// fetch Responses and test fixtures alike. Returns {} for a missing header. Pure.
+export function parseLinkHeader(
+  h: Headers | Record<string, string | string[] | undefined>,
+): CanvasLinks {
+  const raw =
+    typeof (h as Headers)?.get === 'function'
+      ? (h as Headers).get('Link') ?? (h as Headers).get('link')
+      : (h as Record<string, string | string[] | undefined>).Link ??
+        (h as Record<string, string | string[] | undefined>).link;
+  const val = Array.isArray(raw) ? raw.join(', ') : raw;
+  const links: CanvasLinks = {};
+  if (!val) return links;
+  for (const part of String(val).split(',')) {
+    const m = part.match(/<([^>]+)>\s*;\s*rel="?([^"\s;]+)"?/i);
+    if (!m) continue;
+    const rel = m[2].toLowerCase();
+    if (rel === 'current' || rel === 'next' || rel === 'prev' || rel === 'first' || rel === 'last') {
+      links[rel] = m[1];
+    }
+  }
+  return links;
+}
+
+// pageOfUrl extracts the 1-based `page` query param from a Canvas pagination URL
+// (the relations in parseLinkHeader carry absolute URLs). Returns undefined when
+// absent/unparseable. Pure — lets a same-origin proxy client re-request the next
+// page by number without following Canvas's absolute URL directly.
+export function pageOfUrl(url: string | undefined): number | undefined {
+  if (!url) return undefined;
+  const m = url.match(/[?&]page=([^&]+)/);
+  if (!m) return undefined;
+  const n = Number.parseInt(decodeURIComponent(m[1]), 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+// nextPage is the page number to request for the next page, or undefined when
+// there is no `next` relation (the last page). Pure — the ONE way the panel decides
+// whether to keep paginating.
+export function nextPage(links: CanvasLinks): number | undefined {
+  return pageOfUrl(links.next);
+}
+
+// ---- Response parsing -----------------------------------------------------
+//
+// Canvas list endpoints return a bare JSON array of records; detail endpoints
+// return one object. We normalize the snake_case wire fields we surface into small
+// typed shapes at this boundary so nothing downstream touches the wire. Text bodies
+// (syllabus, page body, assignment description, discussion message) are Canvas HTML;
+// we keep them raw here and strip to plain text in course.ts (htmlToText) at render.
+
+function arrayOf(data: any, key?: string): any[] {
+  if (Array.isArray(data)) return data;
+  if (key && Array.isArray(data?.[key])) return data[key];
+  return [];
+}
+
+// One course as it appears in listCourses / getCourse.
+export interface Course {
+  id: number;
+  name: string;
+  courseCode: string;
+  workflowState: string;
+  syllabusBody: string;
+  termName: string;
+}
+
+export function parseCourse(data: any): Course {
+  return {
+    id: Number(data?.id ?? 0),
+    name: String(data?.name ?? ''),
+    courseCode: String(data?.course_code ?? ''),
+    workflowState: String(data?.workflow_state ?? ''),
+    syllabusBody: String(data?.syllabus_body ?? ''),
+    termName: String(data?.term?.name ?? data?.enrollment_term_id ?? ''),
+  };
+}
+
+export function parseCourses(data: any): Course[] {
+  return arrayOf(data, 'courses')
+    .map(parseCourse)
+    .filter((c) => c.id > 0);
+}
+
+// One assignment.
+export interface Assignment {
+  id: number;
+  name: string;
+  description: string;
+  dueAt: string;
+  pointsPossible: number;
+  submissionTypes: string[];
+}
+
+export function parseAssignment(data: any): Assignment {
+  return {
+    id: Number(data?.id ?? 0),
+    name: String(data?.name ?? ''),
+    description: String(data?.description ?? ''),
+    dueAt: String(data?.due_at ?? ''),
+    pointsPossible: Number(data?.points_possible ?? 0),
+    submissionTypes: Array.isArray(data?.submission_types)
+      ? data.submission_types.map((s: any) => String(s))
+      : [],
+  };
+}
+
+export function parseAssignments(data: any): Assignment[] {
+  return arrayOf(data, 'assignments')
+    .map(parseAssignment)
+    .filter((a) => a.id > 0);
+}
+
+// One comment within a submission's thread.
+export interface SubmissionComment {
+  id: number;
+  authorName: string;
+  comment: string;
+  createdAt: string;
+}
+
+function parseSubmissionComment(c: any): SubmissionComment {
+  return {
+    id: Number(c?.id ?? 0),
+    authorName: String(c?.author_name ?? c?.author?.display_name ?? ''),
+    comment: String(c?.comment ?? ''),
+    createdAt: String(c?.created_at ?? ''),
+  };
+}
+
+// One student submission.
+export interface Submission {
+  id: number;
+  userId: number;
+  assignmentId: number;
+  body: string;
+  submittedAt: string;
+  workflowState: string;
+  score: number | null;
+  grade: string;
+  late: boolean;
+  missing: boolean;
+  comments: SubmissionComment[];
+}
+
+export function parseSubmission(data: any): Submission {
+  return {
+    id: Number(data?.id ?? 0),
+    userId: Number(data?.user_id ?? 0),
+    assignmentId: Number(data?.assignment_id ?? 0),
+    body: String(data?.body ?? ''),
+    submittedAt: String(data?.submitted_at ?? ''),
+    workflowState: String(data?.workflow_state ?? ''),
+    score: typeof data?.score === 'number' ? data.score : null,
+    grade: data?.grade === null || data?.grade === undefined ? '' : String(data.grade),
+    late: data?.late === true,
+    missing: data?.missing === true,
+    comments: Array.isArray(data?.submission_comments)
+      ? data.submission_comments.map(parseSubmissionComment)
+      : [],
+  };
+}
+
+export function parseSubmissions(data: any): Submission[] {
+  return arrayOf(data, 'submissions')
+    .map(parseSubmission)
+    .filter((s) => s.id > 0 || s.userId > 0);
+}
+
+// One discussion topic.
+export interface Discussion {
+  id: number;
+  title: string;
+  message: string;
+  postedAt: string;
+  isAnnouncement: boolean;
+}
+
+export function parseDiscussion(data: any): Discussion {
+  return {
+    id: Number(data?.id ?? 0),
+    title: String(data?.title ?? ''),
+    message: String(data?.message ?? ''),
+    postedAt: String(data?.posted_at ?? ''),
+    isAnnouncement: data?.is_announcement === true,
+  };
+}
+
+export function parseDiscussions(data: any): Discussion[] {
+  return arrayOf(data, 'discussion_topics')
+    .map(parseDiscussion)
+    .filter((d) => d.id > 0);
+}
+
+// One wiki page. The list omits the body; the detail (getPage) carries it.
+export interface Page_ {
+  pageId: number;
+  url: string;
+  title: string;
+  body: string;
+  updatedAt: string;
+}
+
+export function parsePage(data: any): Page_ {
+  return {
+    pageId: Number(data?.page_id ?? 0),
+    url: String(data?.url ?? ''),
+    title: String(data?.title ?? ''),
+    body: String(data?.body ?? ''),
+    updatedAt: String(data?.updated_at ?? ''),
+  };
+}
+
+export function parsePages(data: any): Page_[] {
+  return arrayOf(data, 'pages')
+    .map(parsePage)
+    .filter((p) => p.pageId > 0 || p.url.length > 0);
+}
+
+// One module item (a page, assignment, quiz, file, external link, …).
+export interface ModuleItem {
+  id: number;
+  title: string;
+  type: string;
+  position: number;
+}
+
+// One course module, with its items when Canvas inlined them.
+export interface Module {
+  id: number;
+  name: string;
+  position: number;
+  items: ModuleItem[];
+}
+
+function parseModuleItem(i: any): ModuleItem {
+  return {
+    id: Number(i?.id ?? 0),
+    title: String(i?.title ?? ''),
+    type: String(i?.type ?? ''),
+    position: Number(i?.position ?? 0),
+  };
+}
+
+export function parseModule(data: any): Module {
+  return {
+    id: Number(data?.id ?? 0),
+    name: String(data?.name ?? ''),
+    position: Number(data?.position ?? 0),
+    items: Array.isArray(data?.items) ? data.items.map(parseModuleItem) : [],
+  };
+}
+
+export function parseModules(data: any): Module[] {
+  return arrayOf(data, 'modules')
+    .map(parseModule)
+    .filter((m) => m.id > 0);
+}
+
+// One enrollment (a person's role in the course).
+export interface Enrollment {
+  id: number;
+  userId: number;
+  userName: string;
+  type: string;
+  role: string;
+  state: string;
+}
+
+export function parseEnrollment(data: any): Enrollment {
+  return {
+    id: Number(data?.id ?? 0),
+    userId: Number(data?.user_id ?? 0),
+    userName: String(data?.user?.name ?? data?.user?.short_name ?? ''),
+    type: String(data?.type ?? ''),
+    role: String(data?.role ?? ''),
+    state: String(data?.enrollment_state ?? ''),
+  };
+}
+
+export function parseEnrollments(data: any): Enrollment[] {
+  return arrayOf(data, 'enrollments')
+    .map(parseEnrollment)
+    .filter((e) => e.id > 0);
+}
@@ -0,0 +1,167 @@
+// Canvas OAuth 2.0 (Authorization Code Grant) — pure request shaping. The client
+// secret is held by the server (server.ts) and never reaches the browser; these
+// functions build the exact URL/body of each OAuth call so the wire shape is
+// unit-testable without a network round-trip. The token exchange and refresh are
+// each one fetch in the server.
+//
+// Canvas uses form-encoded bodies with client_id + client_secret IN THE BODY (not
+// HTTP Basic) and requires the redirect_uri on the code exchange — the standard
+// OAuth2 web-server shape, documented at
+// canvas.instructure.com/doc/api/file.oauth_endpoints.html. The login host is the
+// institution's own Canvas host (see config.authBase): authorize at
+// /login/oauth2/auth, token at /login/oauth2/token.
+
+import { authBase } from './config.js';
+
+// authorizeUrl is where the install flow sends the user's browser to grant the
+// app. `state` is the CSRF token the server generates and re-checks on callback.
+// Canvas's Authorization Code grant takes response_type=code + client_id +
+// redirect_uri + state; scope is optional (only enforced when the Developer Key
+// enables scope enforcement), so it is only appended when non-empty.
+export function authorizeUrl(args: {
+  host: string;
+  clientId: string;
+  redirectUri: string;
+  scopes?: readonly string[];
+  state: string;
+}): string {
+  const params: Record<string, string> = {
+    client_id: args.clientId,
+    response_type: 'code',
+    redirect_uri: args.redirectUri,
+    state: args.state,
+  };
+  if (args.scopes && args.scopes.length > 0) params.scope = args.scopes.join(' ');
+  const q = new URLSearchParams(params);
+  return `${authBase(args.host)}/login/oauth2/auth?${q.toString()}`;
+}
+
+// A prepared HTTP request: the pieces a single fetch needs. Pure output so a test
+// asserts the form body without opening a socket. Canvas's token endpoint takes
+// application/x-www-form-urlencoded.
+export interface PreparedRequest {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+// tokenUrl is the OAuth token endpoint for a host.
+export function tokenUrl(host: string): string {
+  return `${authBase(host)}/login/oauth2/token`;
+}
+
+// tokenExchange builds the code→token request against the host's
+// /login/oauth2/token. grant_type=authorization_code with the code, the key's
+// credentials, and the SAME redirect_uri that was used on /login/oauth2/auth
+// (Canvas requires it to match). The secret rides only in this server-side body.
+export function tokenExchange(args: {
+  host: string;
+  clientId: string;
+  clientSecret: string;
+  code: string;
+  redirectUri: string;
+}): PreparedRequest {
+  return {
+    url: tokenUrl(args.host),
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      client_id: args.clientId,
+      client_secret: args.clientSecret,
+      redirect_uri: args.redirectUri,
+      code: args.code,
+    }).toString(),
+  };
+}
+
+// refreshExchange builds the refresh-token→token request. Canvas access tokens are
+// short-lived (~1h); a refresh returns a fresh access_token but — unlike Procore —
+// Canvas does NOT rotate the refresh token (it returns none), so the server keeps
+// the original refresh token. No redirect_uri on refresh.
+export function refreshExchange(args: {
+  host: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}): PreparedRequest {
+  return {
+    url: tokenUrl(args.host),
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'refresh_token',
+      client_id: args.clientId,
+      client_secret: args.clientSecret,
+      refresh_token: args.refreshToken,
+    }).toString(),
+  };
+}
+
+// The Canvas person sub-object returned alongside a token (the authorizing user).
+export interface CanvasUser {
+  id: number;
+  name: string;
+}
+
+// The token response we care about. Canvas returns access_token (+ token_type,
+// user, expires_in, and refresh_token ONLY on the initial code exchange).
+// parseTokenResponse validates the one field we must have and surfaces Canvas's
+// own error otherwise.
+export interface CanvasTokenSet {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+  user?: CanvasUser;
+}
+
+export function parseTokenResponse(data: any): CanvasTokenSet {
+  if (!data || typeof data !== 'object') throw new Error('empty token response');
+  if (data.error) {
+    const reason = data.error_description || data.message || data.error;
+    throw new Error(`Canvas OAuth error: ${reason}`);
+  }
+  if (typeof data.access_token !== 'string' || data.access_token.length === 0) {
+    throw new Error('Canvas OAuth response missing access_token');
+  }
+  const user =
+    data.user && typeof data.user === 'object'
+      ? { id: Number(data.user.id ?? 0), name: String(data.user.name ?? '') }
+      : undefined;
+  return {
+    access_token: data.access_token,
+    refresh_token: typeof data.refresh_token === 'string' ? data.refresh_token : undefined,
+    expires_in: typeof data.expires_in === 'number' ? data.expires_in : undefined,
+    token_type: typeof data.token_type === 'string' ? data.token_type : undefined,
+    user,
+  };
+}
+
+// carryRefreshToken applies Canvas's non-rotating refresh semantics: a refresh
+// response omits the refresh token, so the new token set inherits the previous
+// refresh token. Pure — the server calls this after every refresh so the session
+// never loses the ability to refresh again.
+export function carryRefreshToken(next: CanvasTokenSet, previous: CanvasTokenSet): CanvasTokenSet {
+  return next.refresh_token ? next : { ...next, refresh_token: previous.refresh_token };
+}
+
+// tokenExpiresAt computes the absolute epoch-seconds expiry from a token set and
+// the wall-clock second it was minted, applying a safety skew so a request is never
+// sent with a token about to expire mid-flight. Canvas does not return a mint
+// timestamp, so the caller supplies `mintedAt` (recorded when the token was
+// stored). Pure.
+export function tokenExpiresAt(token: CanvasTokenSet, mintedAt: number, skewSeconds = 60): number {
+  const ttl = typeof token.expires_in === 'number' ? token.expires_in : 0;
+  return mintedAt + ttl - skewSeconds;
+}
+
+// isExpired reports whether a token set is at/past its (skew-adjusted) expiry as of
+// `now`, given when it was minted. The server checks this before each API call and
+// refreshes when true. Pure.
+export function isExpired(
+  token: CanvasTokenSet,
+  mintedAt: number,
+  now: number,
+  skewSeconds = 60,
+): boolean {
+  return now >= tokenExpiresAt(token, mintedAt, skewSeconds);
+}
@@ -0,0 +1,166 @@
+// Canvas LMS config — the institution's Canvas host, the Canvas REST API version
+// segment, the api.hanzo.ai model gateway, and the server-side secret set (Canvas
+// OAuth). Endpoints and the bearer choice mirror @hanzo/procore and @hanzo/docusign
+// so the productivity suite stays DRY; the education-specific pieces
+// (course-context windowing, the AI actions) live in course.ts / hanzo.ts /
+// actions.ts, not here.
+
+// ---- Hanzo model gateway --------------------------------------------------
+
+// Where the Hanzo model gateway lives. `@hanzo/ai` defaults here too. /v1 only,
+// never an /api/ prefix (api.hanzo.ai IS the api host).
+export const HANZO_API_BASE_URL = 'https://api.hanzo.ai';
+
+// Default model. A Zen model (qwen3+). Overridable per-request via the picker;
+// the gateway routes it.
+export const DEFAULT_MODEL = 'zen5';
+
+// Public IAM origin that mints Hanzo user tokens, and the OAuth client id an
+// inbound Hanzo token is audienced to (owner-scoping validation via @hanzo/iam).
+export const DEFAULT_IAM_SERVER_URL = 'https://hanzo.id';
+export const DEFAULT_IAM_CLIENT_ID = 'hanzo-canvas';
+
+// localStorage key for the pasted Hanzo API key (`hk-…`) in the web panel. The
+// panel is a static web page (iframe), not a host with roamingSettings, so the
+// zero-setup credential lives in localStorage — same as @hanzo/procore.
+export const APIKEY_STORAGE_KEY = 'hanzo.canvas.apiKey';
+
+// Course text budget. A busy course has many assignments, pages, discussions, and
+// submissions; the whole corpus won't fit a model window and shouldn't be sent.
+// This caps the characters of course text we attach to any one request — chosen so
+// it fits comfortably inside a modern context window alongside the reply, and is
+// honest rather than optimal (we truncate visibly, never drop silently).
+export const COURSE_CHAR_BUDGET = 60_000;
+
+// pickBearer chooses the credential to send to the Hanzo gateway: a pasted API key
+// wins over an OAuth token (an explicit key is a deliberate override), else the
+// token, else empty (anonymous — the gateway still serves public models). Pure —
+// unit-tested.
+export function pickBearer(apiKey: string, oauthToken: string): string {
+  return (apiKey && apiKey.trim()) || (oauthToken && oauthToken.trim()) || '';
+}
+
+// chatCompletionsURL / modelsURL — the model gateway endpoints.
+export function chatCompletionsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/chat/completions`;
+}
+export function modelsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/models`;
+}
+
+// ---- Canvas host + API ----------------------------------------------------
+//
+// Canvas LMS is self-hosted per institution: each school runs its own Canvas at
+// its own host (e.g. `school.instructure.com` or a custom domain). There is no
+// fixed host list — the host is a deployment value, so every Canvas URL (OAuth
+// login + REST API) is built from the configured host. We never hard-code an
+// institution host inline.
+//
+// Docs: canvas.instructure.com/doc/api/file.oauth.html and
+// canvas.instructure.com/doc/api/index.html (REST API).
+
+// normalizeHost strips a scheme, a trailing slash, and any path/query so a raw
+// value like `https://school.instructure.com/` or `school.instructure.com`
+// resolves to the bare host `school.instructure.com`. Pure — the ONE place a host
+// is cleaned, so every URL builder gets a canonical host. Boundary guard.
+export function normalizeHost(raw: string): string {
+  return raw
+    .trim()
+    .replace(/^https?:\/\//i, '')
+    .replace(/\/.*$/, '')
+    .replace(/\/+$/, '');
+}
+
+// authBase turns a host into the OAuth login origin — `/login/oauth2/auth` and
+// `/login/oauth2/token` live here. Pure.
+export function authBase(host: string): string {
+  return `https://${normalizeHost(host)}`;
+}
+
+// The REST API version segment. v1 is Canvas's current (and only) REST version;
+// we never bump to a speculative v2 — one version, forward only. This is Canvas's
+// OWN `/api/v1` path, not a Hanzo gateway path (the /api/ ban is only for
+// api.hanzo.ai, which uses /v1).
+export const REST_API_VERSION = 'v1';
+
+// apiBaseUrl turns a host into the REST root: `https://{host}/api/v1`. Every Canvas
+// API call is built on top of this. Pure — the request wrappers in canvas-api.ts
+// take this string.
+export function apiBaseUrl(host: string): string {
+  return `${authBase(host)}/api/${REST_API_VERSION}`;
+}
+
+// The OAuth scopes the app requests. Canvas only enforces scopes when the
+// Developer Key has "Enforce Scopes" enabled; a standard key ignores the `scope`
+// parameter (permissions follow the authorizing user's Canvas role). We default to
+// none so the app installs against either key type, and document the granular
+// URL-scopes to add (see RECOMMENDED_SCOPES) when enforcement is on. The authorize
+// URL only appends `scope` when this is non-empty.
+export const OAUTH_SCOPES = [] as const;
+
+// RECOMMENDED_SCOPES documents the exact Canvas URL-scopes to request when the
+// Developer Key enforces scopes — the read surface this app uses plus the two
+// gated writes. Not sent by default (see OAUTH_SCOPES); referenced by the README
+// and available for a deployment that opts into scope enforcement.
+export const RECOMMENDED_SCOPES = [
+  'url:GET|/api/v1/courses',
+  'url:GET|/api/v1/courses/:id',
+  'url:GET|/api/v1/courses/:course_id/assignments',
+  'url:GET|/api/v1/courses/:course_id/assignments/:id',
+  'url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions',
+  'url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id',
+  'url:GET|/api/v1/courses/:course_id/discussion_topics',
+  'url:GET|/api/v1/courses/:course_id/pages',
+  'url:GET|/api/v1/courses/:course_id/pages/:url_or_id',
+  'url:GET|/api/v1/courses/:course_id/modules',
+  'url:GET|/api/v1/courses/:course_id/enrollments',
+  'url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id',
+  'url:POST|/api/v1/courses/:course_id/discussion_topics',
+] as const;
+
+// ---- Server-side configuration (Canvas OAuth) -----------------------------
+//
+// These are read from the environment by src/server.ts. They NEVER reach the
+// browser bundle: the client id and host are public, but the client secret is
+// server-only and is validated to be present before the server will start
+// (readServerConfig throws on a missing secret). This is the ONLY place the secret
+// exists.
+
+export interface ServerConfig {
+  /** Canvas institution host, e.g. `school.instructure.com` (bare, normalized). */
+  canvasHost: string;
+  /** Canvas Developer Key client id (public). */
+  canvasClientId: string;
+  /** Canvas Developer Key client secret (SERVER ONLY — token exchange + refresh). */
+  canvasClientSecret: string;
+  /** OAuth redirect registered on the key (e.g. https://canvas.hanzo.ai/oauth/callback). */
+  canvasRedirectUri: string;
+  /** Listen port. */
+  port: number;
+}
+
+// readServerConfig fails fast (throws) if a required Canvas value is missing — a
+// server that cannot exchange OAuth codes (or does not know which Canvas host to
+// call) must not pretend to start. Pure given an env map, so it is unit-tested
+// without touching process.env. The host is normalized at this one boundary.
+export function readServerConfig(env: Record<string, string | undefined>): ServerConfig {
+  const canvasHost = env.CANVAS_HOST;
+  const canvasClientId = env.CANVAS_CLIENT_ID;
+  const canvasClientSecret = env.CANVAS_CLIENT_SECRET;
+  const canvasRedirectUri = env.CANVAS_REDIRECT_URI;
+  const missing: string[] = [];
+  if (!canvasHost) missing.push('CANVAS_HOST');
+  if (!canvasClientId) missing.push('CANVAS_CLIENT_ID');
+  if (!canvasClientSecret) missing.push('CANVAS_CLIENT_SECRET');
+  if (!canvasRedirectUri) missing.push('CANVAS_REDIRECT_URI');
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment: ${missing.join(', ')}`);
+  }
+  return {
+    canvasHost: normalizeHost(canvasHost!),
+    canvasClientId: canvasClientId!,
+    canvasClientSecret: canvasClientSecret!,
+    canvasRedirectUri: canvasRedirectUri!,
+    port: Number(env.PORT) || 8791,
+  };
+}
@@ -0,0 +1,251 @@
+// Course-context assembly — PURE, host-agnostic, fully unit-testable. Turns the
+// typed Canvas records (course/syllabus, modules, assignments, pages, discussions,
+// submissions, enrollments) into the plain text an AI action reads, windowed to a
+// character budget so a busy course never overflows the model or gets sent silently
+// truncated.
+//
+// There is ONE windowing contract, identical in spirit to @hanzo/procore's project
+// windowing: render ordered blocks, walk them in order, stop at the budget, always
+// include at least the first block, and report `truncated` honestly. The only
+// education-specific parts are how a record renders to a block and the HTML→text
+// step (Canvas content — syllabus, page bodies, assignment descriptions, discussion
+// messages — is HTML).
+
+import type {
+  Assignment,
+  Course,
+  Discussion,
+  Enrollment,
+  Module,
+  Page_,
+  Submission,
+} from './canvas-api.js';
+import { COURSE_CHAR_BUDGET } from './config.js';
+
+// ---- HTML → text ----------------------------------------------------------
+
+// htmlToText reduces Canvas rich-text HTML to readable plain text: block elements
+// become line breaks, tags are stripped, the common named/numeric entities are
+// decoded, and whitespace is collapsed. Deliberately small and dependency-free (no
+// DOM) — Canvas bodies are trusted-institution content we only need to READ, not
+// render, so a full sanitizer/ parser would be over-engineering. Pure.
+export function htmlToText(html: string): string {
+  if (!html) return '';
+  return html
+    .replace(/<\s*(br|\/p|\/div|\/li|\/h[1-6]|\/tr)\s*\/?\s*>/gi, '\n')
+    .replace(/<\s*li[^>]*>/gi, '• ')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .split('\n')
+    .map((line) => line.trim())
+    .join('\n')
+    .trim();
+}
+
+// clamp trims a rendered body to a maximum length with an ellipsis so one giant
+// page/syllabus can't dominate the budget before windowing even runs. Pure.
+function clamp(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max).trimEnd()}…` : text;
+}
+
+// Per-body cap: a single HTML body is trimmed to this before it becomes a block, so
+// the windowing budget sees comparable blocks rather than one 40k-char page.
+const BODY_CAP = 4_000;
+
+// ---- Record → text block --------------------------------------------------
+
+// renderCourseOverview turns the course + its syllabus into the lead block: the
+// course identity and the (HTML-stripped, clamped) syllabus text.
+export function renderCourseOverview(course: Course): string {
+  const lines: string[] = [];
+  const head = `${course.name}${course.courseCode ? ` (${course.courseCode})` : ''}`.trim();
+  lines.push(head);
+  const meta: string[] = [];
+  if (course.termName) meta.push(`Term: ${course.termName}`);
+  if (course.workflowState) meta.push(`State: ${course.workflowState}`);
+  if (meta.length) lines.push(meta.join(' · '));
+  const syllabus = htmlToText(course.syllabusBody);
+  if (syllabus) lines.push(`Syllabus:\n${clamp(syllabus, BODY_CAP)}`);
+  return lines.join('\n');
+}
+
+// renderAssignment turns one assignment into a labelled block.
+export function renderAssignment(a: Assignment): string {
+  const head = `Assignment: ${a.name}`.trim();
+  const meta: string[] = [];
+  if (a.dueAt) meta.push(`Due: ${a.dueAt}`);
+  if (a.pointsPossible) meta.push(`Points: ${a.pointsPossible}`);
+  if (a.submissionTypes.length) meta.push(`Submit: ${a.submissionTypes.join(', ')}`);
+  const lines = [meta.length ? `${head}\n${meta.join(' · ')}` : head];
+  const desc = htmlToText(a.description);
+  if (desc) lines.push(clamp(desc, BODY_CAP));
+  return lines.join('\n');
+}
+
+// renderSubmission turns one student submission into a labelled block, including
+// the score/status and any existing comment thread (order preserved).
+export function renderSubmission(s: Submission): string {
+  const lines: string[] = [];
+  const flags = [s.late ? 'late' : '', s.missing ? 'missing' : ''].filter(Boolean).join(', ');
+  const head = `Submission (user ${s.userId})${flags ? ` [${flags}]` : ''}`;
+  lines.push(head);
+  const meta: string[] = [];
+  if (s.workflowState) meta.push(`Status: ${s.workflowState}`);
+  if (s.score !== null) meta.push(`Score: ${s.score}`);
+  if (s.grade) meta.push(`Grade: ${s.grade}`);
+  if (s.submittedAt) meta.push(`Submitted: ${s.submittedAt}`);
+  if (meta.length) lines.push(meta.join(' · '));
+  const body = htmlToText(s.body);
+  if (body) lines.push(`Response: ${clamp(body, BODY_CAP)}`);
+  for (const c of s.comments) {
+    const who = c.authorName ? ` (${c.authorName})` : '';
+    if (c.comment) lines.push(`Comment${who}: ${c.comment.trim()}`);
+  }
+  return lines.join('\n');
+}
+
+// renderDiscussion turns one discussion topic into a labelled block.
+export function renderDiscussion(d: Discussion): string {
+  const kind = d.isAnnouncement ? 'Announcement' : 'Discussion';
+  const head = `${kind}: ${d.title}`.trim();
+  const body = htmlToText(d.message);
+  return body ? `${head}\n${clamp(body, BODY_CAP)}` : head;
+}
+
+// renderPage turns one wiki page into a labelled block (title + stripped body).
+export function renderPage(p: Page_): string {
+  const head = `Page: ${p.title || p.url}`.trim();
+  const body = htmlToText(p.body);
+  return body ? `${head}\n${clamp(body, BODY_CAP)}` : head;
+}
+
+// renderModule turns one module + its items into a labelled block.
+export function renderModule(m: Module): string {
+  const head = `Module: ${m.name}`.trim();
+  const items = m.items.map((i) => `  - ${i.title}${i.type ? ` [${i.type}]` : ''}`).filter(Boolean);
+  return items.length ? `${head}\n${items.join('\n')}` : head;
+}
+
+// renderEnrollment turns one enrollment into a single labelled line.
+export function renderEnrollment(e: Enrollment): string {
+  const who = e.userName || `user ${e.userId}`;
+  const role = e.role || e.type;
+  return `${who}${role ? ` — ${role}` : ''}${e.state ? ` (${e.state})` : ''}`;
+}
+
+// ---- Windowing to a budget ------------------------------------------------
+
+// A named group of rendered blocks — a section of the course context (e.g.
+// "Assignments", "Modules"). The assembler concatenates sections in the order given
+// and windows the whole thing to the budget.
+export interface Section {
+  title: string;
+  blocks: string[];
+}
+
+// The windowed course context: the rendered text, how many blocks were available vs
+// included, and whether anything was dropped (so the prompt and UI can say so
+// honestly).
+export interface CourseContext {
+  text: string;
+  totalBlocks: number;
+  includedBlocks: number;
+  truncated: boolean;
+}
+
+// buildCourseContext concatenates sections IN ORDER and caps the rendered text at
+// `budget` characters. It walks blocks in order (across sections) and stops when
+// adding the next block would exceed the budget — always including at least the
+// first block (hard-cut to the budget if that one block alone is over). `truncated`
+// is true whenever not every available block made it in. Pure and total:
+// deterministic, no I/O. This is the ONE windowing algorithm for the package — the
+// same "fit ordered text to a budget" contract as @hanzo/procore.
+export function buildCourseContext(
+  sections: Section[],
+  budget: number = COURSE_CHAR_BUDGET,
+): CourseContext {
+  const totalBlocks = sections.reduce((n, s) => n + s.blocks.length, 0);
+  if (totalBlocks === 0) {
+    return { text: '', totalBlocks: 0, includedBlocks: 0, truncated: false };
+  }
+
+  const parts: string[] = [];
+  let used = 0;
+  let included = 0;
+  let hardCut = false;
+
+  outer: for (const section of sections) {
+    if (section.blocks.length === 0) continue;
+    // The section header is charged to the first block that fits under it.
+    let headerPending = `## ${section.title}\n`;
+    for (const block of section.blocks) {
+      const prefix = parts.length === 0 ? '' : '\n\n';
+      const addition = prefix + headerPending + block;
+      if (used + addition.length > budget) {
+        if (parts.length === 0) {
+          // First block alone overflows — hard-cut it to the budget so we always
+          // send something rather than an empty context.
+          const solo = (headerPending + block).slice(0, budget);
+          parts.push(solo);
+          used = solo.length;
+          included = 1;
+          hardCut = true;
+        }
+        break outer;
+      }
+      parts.push(addition);
+      used += addition.length;
+      included += 1;
+      headerPending = ''; // header only precedes the first block of the section
+    }
+  }
+
+  const truncated = included < totalBlocks || hardCut;
+  return { text: parts.join(''), totalBlocks, includedBlocks: included, truncated };
+}
+
+// contextNote is the one honest sentence prepended to the course text so the model
+// (and, echoed in the panel, the user) knows the scope of what it sees. Never claim
+// the whole course was sent when it wasn't. Pure.
+export function contextNote(ctx: CourseContext): string {
+  if (ctx.totalBlocks === 0) return 'No course records were available.';
+  return ctx.truncated
+    ? `Course records: ${ctx.includedBlocks} of ${ctx.totalBlocks} items (truncated to fit — answer only from what is shown and say so if the omitted part is needed).`
+    : `Course records: all ${ctx.totalBlocks} item${ctx.totalBlocks === 1 ? '' : 's'}.`;
+}
+
+// ---- Convenience section builders -----------------------------------------
+//
+// These turn a typed record list into a Section, so a caller (server or panel)
+// assembles a course context in a couple of lines. Kept here (pure) so the same
+// section shapes feed both surfaces and the tests.
+
+export function courseSection(course: Course, title = 'Course'): Section {
+  return { title, blocks: [renderCourseOverview(course)] };
+}
+export function moduleSection(modules: Module[], title = 'Modules'): Section {
+  return { title, blocks: modules.map(renderModule) };
+}
+export function assignmentSection(assignments: Assignment[], title = 'Assignments'): Section {
+  return { title, blocks: assignments.map(renderAssignment) };
+}
+export function pageSection(pages: Page_[], title = 'Pages'): Section {
+  return { title, blocks: pages.map(renderPage) };
+}
+export function discussionSection(discussions: Discussion[], title = 'Discussions'): Section {
+  return { title, blocks: discussions.map(renderDiscussion) };
+}
+export function submissionSection(submissions: Submission[], title = 'Submissions'): Section {
+  return { title, blocks: submissions.map(renderSubmission) };
+}
+export function enrollmentSection(enrollments: Enrollment[], title = 'Enrollments'): Section {
+  return { title, blocks: enrollments.map(renderEnrollment) };
+}
@@ -0,0 +1,145 @@
+// The Hanzo call and its request/response shaping over a COURSE — thin over the
+// published `@hanzo/ai` headless client, host-agnostic, and fully unit-testable (no
+// Canvas SDK, no DOM). The panel and the server are the glue that read a course's
+// records and hand them here. Speaks the OpenAI-compatible /v1 wire protocol the
+// whole Hanzo suite uses (identical to @hanzo/procore) so the gateway sees one shape
+// from every surface.
+//
+// @hanzo/ai@^0.2.0 IS the headless client: createAiClient({ baseUrl, token }) →
+// .chat.completions.create({ model, messages }) + .models.list(). We import it and
+// do NOT reimplement the transport. This module adds only the course-aware prompt
+// assembly + the single `ask` primitive the actions layer on.
+
+import {
+  createAiClient,
+  type AiClient,
+  type ChatCompletion,
+  type ChatCompletionMessage,
+} from '@hanzo/ai';
+import { DEFAULT_MODEL, HANZO_API_BASE_URL } from './config.js';
+import { contextNote, type CourseContext } from './course.js';
+
+// SYSTEM_PROMPT grounds every answer in the course records. It forbids inventing
+// facts nobody recorded (the failure mode that makes a teaching assistant
+// untrustworthy), keeps student data handled respectfully, and stays honest about
+// truncated context. It states plainly that the output is a DRAFT for an educator to
+// review — not an authoritative grade, decision, or the final word to a student.
+export const SYSTEM_PROMPT =
+  'You are Hanzo AI, an assistant that helps instructors and teaching staff work ' +
+  'with their Canvas course — the syllabus, modules, assignments, pages, ' +
+  'discussions, and student submissions. Work ONLY from the course records provided ' +
+  'below — never invent assignments, due dates, grades, submissions, or facts that ' +
+  'are not supported by the text. Be concise, precise, and constructive; when you ' +
+  'reference student work, be specific and fair. If the records are marked truncated ' +
+  'and a complete answer needs the omitted part, say so plainly rather than guessing. ' +
+  'Everything you produce — feedback, questions, announcements, summaries — is a ' +
+  'DRAFT for an educator to review and edit before it reaches a student; it is not an ' +
+  'authoritative grade or decision.';
+
+// ---- Prompt assembly ------------------------------------------------------
+
+// Optional structured context about the course (name, code, term) the Canvas API
+// supplies. Attached as a short header above the records so answers can reference the
+// course without the model guessing.
+export interface CourseMeta {
+  name?: string;
+  courseCode?: string;
+  term?: string;
+}
+
+function courseHeader(meta: CourseMeta | undefined): string {
+  if (!meta) return '';
+  const parts: string[] = [];
+  if (meta.name) parts.push(`Course: ${meta.name}`);
+  if (meta.courseCode) parts.push(`Code: ${meta.courseCode}`);
+  if (meta.term) parts.push(`Term: ${meta.term}`);
+  return parts.length > 0 ? parts.join('\n') + '\n\n' : '';
+}
+
+// buildMessages turns a task (the user's question, or one of the action prompts)
+// plus the windowed course context + optional metadata into the OpenAI-compatible
+// message list. The records are fenced so the model treats them as data, not
+// instructions, and the honest context note rides inside the user turn so it is never
+// lost. Pure — unit-tested.
+export function buildMessages(
+  task: string,
+  ctx: CourseContext,
+  meta?: CourseMeta,
+): ChatCompletionMessage[] {
+  const system: ChatCompletionMessage = { role: 'system', content: SYSTEM_PROMPT };
+  const header = courseHeader(meta);
+  const user: ChatCompletionMessage = {
+    role: 'user',
+    content:
+      `${header}${contextNote(ctx)}\n\n` +
+      `---- course records ----\n${ctx.text}\n---- end course records ----\n\n` +
+      `---- task ----\n${task}`,
+  };
+  return [system, user];
+}
+
+// extractContent pulls the assistant text out of a @hanzo/ai ChatCompletion,
+// tolerating the string-or-parts content shape the OpenAI schema allows. Throws on
+// empty content so callers surface the real gateway state. Pure — unit-tested.
+export function extractContent(res: ChatCompletion): string {
+  const msg = res?.choices?.[0]?.message;
+  const content = msg?.content;
+  let text = '';
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content.map((part) => (part?.type === 'text' ? part.text : '')).join('');
+  }
+  if (text.length === 0) throw new Error('Hanzo API returned no content');
+  return text;
+}
+
+// ---- The single call path -------------------------------------------------
+
+export interface AskOptions {
+  model?: string;
+  temperature?: number;
+  token?: string;
+  baseURL?: string;
+  /** Injected client (tests). Defaults to a real createAiClient. */
+  client?: AiClient;
+  signal?: AbortSignal;
+}
+
+// client resolves the @hanzo/ai client for a call: an injected one (tests) or a fresh
+// createAiClient pointed at the gateway with the caller's bearer.
+function client(opts: AskOptions): AiClient {
+  return (
+    opts.client ?? createAiClient({ token: opts.token, baseUrl: opts.baseURL ?? HANZO_API_BASE_URL })
+  );
+}
+
+// ask runs ONE non-streaming completion over a course and returns the answer. This
+// is the single path from every Canvas surface to the model — the actions, a freeform
+// question, and any server-side call all funnel here. token may be empty (the gateway
+// serves anonymous/limited models).
+export async function ask(
+  task: string,
+  ctx: CourseContext,
+  meta: CourseMeta | undefined,
+  opts: AskOptions = {},
+): Promise<string> {
+  const res = await client(opts).chat.completions.create(
+    {
+      model: opts.model ?? DEFAULT_MODEL,
+      messages: buildMessages(task, ctx, meta),
+      stream: false,
+      ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+    },
+    { signal: opts.signal },
+  );
+  return extractContent(res);
+}
+
+// listModels returns the model ids the caller may route to, from /v1/models via the
+// headless client. The endpoint is org-scoped by the bearer; an empty token lists
+// public models.
+export async function listModels(opts: AskOptions = {}): Promise<string[]> {
+  const models = await client(opts).models.list({ signal: opts.signal });
+  return models.map((m) => m.id);
+}
--- a/Show More
+++ b/Show More
				`@@ -1 +0,0 @@`
				`export async function embed(params: any): Promise<any> { return { embeddings: [] }; }`
				`@@ -1 +0,0 @@`
				`export async function generateObject(params: any): Promise<any> { return {}; }`
				`@@ -1 +0,0 @@`
				`export async function* generateStream(params: any): AsyncIterableIterator<any> { yield { type: 'done' }; }`
				`@@ -1 +0,0 @@`
				`export async function generateText(params: any): Promise<any> { return { text: '' }; }`
				`@@ -1 +0,0 @@`
				`export const bedrock = (config: any) => ({ name: 'bedrock', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`
				`@@ -1 +0,0 @@`
				`export const cohere = (config: any) => ({ name: 'cohere', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`
				`@@ -1 +0,0 @@`
				`export const google = (config: any) => ({ name: 'gemini', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`
				`@@ -1 +0,0 @@`
				`export const hanzo = (config: any) => ({ name: 'hanzo', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`
				`@@ -1 +0,0 @@`
				`export const mistral = (config: any) => ({ name: 'mistral', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`
				`@@ -1 +0,0 @@`
				`export const vertex = (config: any) => ({ name: 'vertex', async complete(p: any) { return { content: '' }; }, async *stream(p: any) { yield { type: 'done' as const }; } });`