feat: add the official AI Assistant module

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: sodium
+          coverage: none
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install PHP dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Verify PHP and package contracts
+        run: |
+          composer run lint
+          composer run test
+          vendor/bin/invoiceshelf-module validate-module module.json
+          vendor/bin/invoiceshelf-module validate-package .
+
+      - name: Verify frontend
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm run lint
+          pnpm exec tsc --noEmit
+          pnpm run build
+          git diff --exit-code -- dist

.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: Release module
+
+on:
+  push:
+    tags:
+      - '*'
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    uses: InvoiceShelf/modules/.github/workflows/module-release.yml@3.3.0
+    with:
+      channel: stable
+    secrets: inherit

.gitignore

@@ -0,0 +1,9 @@
+/vendor/
+/node_modules/
+/.phpunit.cache/
+/coverage/
+/*.zip
+/release-manifest.json
+/release-manifest.canonical.json
+/release-manifest.sig
+

AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md
+
+This is the official InvoiceShelf AI Assistant module. Read the parent devenv `AGENTS.md` and the InvoiceShelf 3.x `AGENTS.md` before making changes.
+
+- PHP 8.4, Laravel 13, PHPUnit 12, Vue 3, TypeScript, and Vite.
+- Keep business queries behind `InvoiceShelf\\Modules\\Contracts\\Host` interfaces; module code must not import InvoiceShelf Eloquent models.
+- Use the SDK AI driver ABI under `InvoiceShelf\\Modules\\Ai`.
+- Keep the module optional: all UI must register through the host extension API and all backend routes must disappear when disabled.
+- Preserve the existing `ai_conversations` and `ai_messages` schema and migration filename.
+- Run `composer run lint`, `composer run test`, `pnpm run build`, and package validation before release.

README.md

@@ -0,0 +1,26 @@
+# InvoiceShelf AI Assistant
+
+The official free AI Assistant module for InvoiceShelf 3.x. It provides the in-app assistant, read-only business-data tools, and rich-text generation while keeping AI dependencies out of the core application.
+
+Users supply and fund their own OpenRouter API key. The module itself is free and open source under AGPL-3.0-only.
+
+## Development
+
+```bash
+composer install
+pnpm install --frozen-lockfile
+composer run lint
+composer run test
+pnpm run build
+vendor/bin/invoiceshelf-module validate-package .
+```
+
+Compiled assets in `dist/` are committed because InvoiceShelf installs immutable packages without running Composer or Node package managers.
+
+## Data lifecycle
+
+Disabling or uninstalling the module normally preserves conversations and configuration. If an administrator explicitly selects **Remove module data**, the cleanup hook removes legacy settings and the reversible migration removes the AI conversation tables.
+
+## Releases
+
+Push an exact SemVer tag matching `module.json`, such as `1.0.0`. The release workflow builds and validates a deterministic signed package before registering it with the InvoiceShelf marketplace.