Initial public push: docs cosmos v4 + AI module + framework groundwork

This is the snapshot the production landing site (nibiru-framework.com) is
deployed from. Brings together the recent splash + docs migration to the v4
"Cosmos" design system, the new in-framework AI module, and the framework
groundwork that backs the framework-reference extraction.

What lands:
- docs/: Astro + Starlight site with the v4 dark cosmic palette, GalaxyHero
  canvas constellation, Mission Control chat (wired to /api/oracle →
  api.neuronetz.ai via providers.mjs Ollama), 5-panel MMVC stage
  (Model · AI · Module · Controller · View), translated EN/DE/JA/ES/FR
  content, PWA + sitemap + llms.txt + Umami analytics.
- docs/design-system/: canonical mockup bundle (source/index-v2.html for
  splash, source/docs-system.html + preview/ for docs, SPEC.md, tokens).
- docs/scripts/extraction/framework-reference-v2.md: deep framework
  reference (~1.6k lines, file:line citations, every public factory and
  idiom — basis for the LoRA training corpus.
- application/module/ai/: AI module with chat / embed / RAG / agent
  plugins, plus pdoQuery / httpGet / fileRead tools and Modelfile +
  smoke-test in training/.
- application/module/users/: user / ACL / form-factory traits used as the
  reference plugin pattern for the framework docs.
- application/settings/config/database/: schema + seed migrations
  including the AI module tables (200–203).
- Form factory + autogenerator changes the framework-reference-v2 covers.

Production secrets stay out: docs/.env, settings.production.ini and
ai.production.ini are all gitignored (.example files are in tree).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

application/module/ai/plugins/tools/pdoQuery.php

@@ -0,0 +1,67 @@
+<?php
+namespace Nibiru\Module\Ai\Plugins\Tools;
+
+use Nibiru\Module\Ai\Plugins\Tool;
+use Nibiru\Pdo;
+
+/**
+ * Read-only SQL query tool. Lets an agent ask the database questions like
+ * "how many active users?" without giving it write access.
+ *
+ *   $agent->withTools([new \Nibiru\Module\Ai\Plugins\Tools\PdoQuery()])
+ *         ->run('How many users registered last week?');
+ *
+ * Safety: rejects anything that looks like INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER.
+ * If you need write access, write a more privileged subclass with an audit trail.
+ */
+class PdoQuery extends Tool
+{
+    public function name(): string { return 'pdo_query'; }
+
+    public function description(): string
+    {
+        return 'Run a single read-only SQL SELECT against the application database. '
+             . 'Use for counts, aggregates, lookups. Returns rows as JSON.';
+    }
+
+    public function schema(): array
+    {
+        return [
+            'sql' => [
+                'type' => 'string',
+                'description' => 'A single SELECT statement. Use placeholders (:name) for dynamic values.',
+                'required' => true,
+            ],
+            'params' => [
+                'type' => 'object',
+                'description' => 'Optional parameter bindings, e.g. {":id": 42}.',
+                'required' => false,
+            ],
+        ];
+    }
+
+    public function execute(array $args): mixed
+    {
+        $sql = trim((string) ($args['sql'] ?? ''));
+        if ($sql === '') return 'ERROR: empty SQL';
+        if (!preg_match('/^\s*SELECT\s/i', $sql)) {
+            return 'ERROR: only SELECT is permitted by pdo_query';
+        }
+        if (preg_match('/;\s*\S/', $sql)) {
+            return 'ERROR: only a single statement is permitted';
+        }
+        if (preg_match('/\b(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE)\b/i', $sql)) {
+            return 'ERROR: write/DDL operations are blocked';
+        }
+
+        try {
+            $params = is_array($args['params'] ?? null) ? $args['params'] : [];
+            $rows = Pdo::fetchAll($sql, $params);
+            // Cap the response so the agent doesn't choke on huge results.
+            $rows = array_slice($rows, 0, 50);
+            return json_encode($rows, JSON_UNESCAPED_UNICODE);
+        } catch (\Throwable $e) {
+            return 'ERROR: ' . $e->getMessage();
+        }
+    }
+}