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/fileRead.php

@@ -0,0 +1,51 @@
+<?php
+namespace Nibiru\Module\Ai\Plugins\Tools;
+
+use Nibiru\Module\Ai\Plugins\Tool;
+
+/**
+ * Read a project file by path (relative to the application root). Lets
+ * the agent quote real source when answering "where is X defined?" type
+ * questions. Read-only. No path-traversal — `..` is blocked.
+ */
+class FileRead extends Tool
+{
+    public function name(): string { return 'file_read'; }
+
+    public function description(): string
+    {
+        return 'Read a file from the project. Path is relative to the application root '
+             . '(the directory containing index.php). Returns up to 8 KB.';
+    }
+
+    public function schema(): array
+    {
+        return [
+            'path' => [
+                'type' => 'string',
+                'description' => 'Relative path, e.g. "application/controller/loginController.php".',
+                'required' => true,
+            ],
+        ];
+    }
+
+    public function execute(array $args): mixed
+    {
+        $path = (string) ($args['path'] ?? '');
+        if ($path === '' || str_contains($path, '..')) {
+            return 'ERROR: invalid path';
+        }
+        // Application root = three levels up from this plugin file:
+        //   application/module/ai/plugins/tools/fileRead.php
+        //   ↑       ↑      ↑    ↑       ↑      ↑
+        //   app    module  ai   plugins tools  this
+        $root = realpath(__DIR__ . '/../../../../../');
+        if ($root === false) return 'ERROR: cannot resolve app root';
+        $abs = realpath($root . DIRECTORY_SEPARATOR . $path);
+        if ($abs === false || !is_file($abs)) return 'ERROR: file not found';
+        if (strpos($abs, $root) !== 0) return 'ERROR: path escapes root';
+        $body = (string) file_get_contents($abs);
+        if (strlen($body) > 8192) $body = substr($body, 0, 8192) . "\n…[truncated]";
+        return $body;
+    }
+}