gina 0.3.7-alpha.1 → 0.3.7-alpha.3

package/.github/workflows/security.yml

@@ -7,8 +7,8 @@ on:
     branches: [develop, master]
 
 jobs:
-  claude-leak-check:
-    name: Claude-leak scan
+  local-leak-check:
+    name: Local-tool leak scan
     runs-on: ubuntu-latest
 
     steps:
@@ -16,17 +16,17 @@ jobs:
 
       # #S6 — Backs up the local pre-commit hook (#S5) and the publish-boundary
       # gate in prepare_version.js (#S3). Fails the build if any tracked path
-      # matches (^|/)(CLAUDE\.md|\.claude[a-z]*). Also retroactively catches
+      # matches local-tool configuration paths. Also retroactively catches
       # leaks that landed before the active defenses were wired.
-      - name: Scan tracked files for Claude-related paths
+      - name: Scan tracked files for local-tool paths
         run: |
           matches=$(git ls-files | grep -iE '(^|/)(CLAUDE\.md|\.claude[a-z]*)' || true)
           if [ -n "$matches" ]; then
-            echo "::error::Claude-related paths detected in git index:"
+            echo "::error::local-tool paths detected in git index:"
             echo "$matches" | sed 's/^/  - /'
             echo ""
             echo "These paths must never be tracked. Remove with: git rm --cached <path>"
             echo "If pushed already, scrub history with git filter-repo."
             exit 1
           fi
-          echo "OK: no Claude-related paths in git index."
+          echo "OK: no local-tool paths in git index."

package/.github/workflows/test.yml

@@ -29,6 +29,23 @@ jobs:
           npm install --ignore-scripts
           ln -sf $(pwd) node_modules/gina
 
+      - name: Prepare framework dependencies
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          FW_DIR="framework/v${VERSION}"
+          if [ ! -f "${FW_DIR}/package.json" ]; then
+            cat > "${FW_DIR}/package.json" <<EOF
+          {
+            "name": "gina-framework",
+            "version": "${VERSION}",
+            "dependencies": {
+              "@rhinostone/swig": "^1.6.0"
+            }
+          }
+          EOF
+          fi
+          (cd "${FW_DIR}" && npm install --ignore-scripts)
+
       - name: Run tests
         run: |
           node --test \

package/.playwright-mcp/console-2026-04-22T21-42-03-731Z.log

@@ -0,0 +1,2 @@
+[     112ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ http://127.0.0.1:41724/_gina/assets/routing.json:0
+[     114ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ http://127.0.0.1:41724/favicon.ico:0

package/.playwright-mcp/page-2026-04-22T21-42-03-861Z.yml

@@ -0,0 +1,3 @@
+- generic [active] [ref=e1]:
+  - heading "gina PSL browser smoke" [level=1] [ref=e2]
+  - generic [ref=e3]: waiting…

package/.playwright-mcp/page-2026-04-22T21-44-40-373Z.yml

@@ -0,0 +1,3 @@
+- generic [active] [ref=e1]:
+  - heading "gina PSL browser smoke" [level=1] [ref=e2]
+  - generic [ref=e3]: Domain ready; psl loaded via RequireJS OK | input="example.com" expected="example.com" actual="example.com" OK | input="sub.example.com" expected="example.com" actual="example.com" OK | input="https://www.google.co.uk/blah" expected="google.co.uk" actual="google.co.uk" OK | input="https://my-bucket.s3.af-south-1.amazon.co.za/puppy.png" expected="amazon.co.za" actual="amazon.co.za" OK | input="Mac-mini.local" expected="Mac-mini.local" actual="Mac-mini.local" OK | input="frontend.myproject.beta.Mac-mini.local" expected="Mac-mini.local" actual="Mac-mini.local" OK | input="api.default.svc.cluster.local" expected="cluster.local" actual="cluster.local" OK | input="192.168.1.5" expected="192.168.1.5" actual="192.168.1.5" OK | input="localhost" expected="localhost" actual="localhost" OK | input="" expected="" actual="" OK | input="россия.xn--p1ai" expected="xn--h1alffa9f.xn--p1ai" actual="xn--h1alffa9f.xn--p1ai" ALL PASS

package/AUTHORS

@@ -1,6 +1,6 @@
 # Authors (sorted alphabetically)
 
-John Doe <fabrice.delaneau@gina.io>
+Fabrice DELANEAU <fabrice.delaneau@gina.io>
 Martin Luther ETOUMAN <martin-luther.etouman@gina.io>
 
 # Contributors (sorted alphabetically)

package/CHANGELOG.md

@@ -6,6 +6,64 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.7-alpha.3 - 2026-04-23 (npm only — no git tag)
+### Added
+* The nunjucks render path now registers Gina's built-in filter registry automatically. Bundles with `render.engine: "nunjucks"` get the same 7 filters as the swig path — `getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears` — with no manual `env.addFilter()` calls needed. Templates can use `{{ 'home' | getUrl }}`, `{{ body | nl2br | safe }}`, or date helpers out of the box. User-registered filters on top (`env.addFilter('upper', fn)`) coexist with the built-in registry. Closes the most user-visible gap left by the 0.3.7-alpha.2 nunjucks MVP.
+* Bundles with `render.engine: "nunjucks"` now get automatic asset injection — the same way swig bundles do. Stylesheets, scripts, external plugins, and the Gina loader script are placed into the rendered HTML without any manual `<link>` or `<script>` wiring in layouts. Templates can still opt in explicitly via `{{ page.view.stylesheets | safe }}` and `{{ page.view.scripts | safe }}` — when either is used, auto-injection is skipped for that slot so tags never appear twice. `javascriptsDeferEnabled` moves scripts to `<head>` instead of before `</body>`, and `javascriptsExcluded: "**"` suppresses the loader. XHR / popin responses (`isWithoutLayout`) ship only the common-gina assets, matching swig-side behaviour. Closes the biggest semantic gap left by the 0.3.7-alpha.2 nunjucks MVP.
+### Changed
+* Swapped lib/domain from a vendored MPL-2.0 Public Suffix List (`framework/v*/lib/domain/dist/*.dat`) to the MIT-licensed `psl@^1.15.0` npm package. The public API is preserved — `new Domain()` / `new Domain(cb)` + `getRootDomain(host).value` / `.isSLD` / `.isRegisteredTldOrSld` all behave the same on recognised domains. Under the hood, the wrapper delegates to `psl.parse()` and falls back to the hostname's last two labels for unknown suffixes (matches today's behaviour on `.local`, `.localdomain`, cluster-internal pseudo-TLDs). IPv4 literals (`192.168.1.5`), IPv6 literals (`[::1]`), and `undefined`/`null` inputs are now handled defensively rather than producing broken values or throwing. Browser-side, the psl UMD is vendored and exposed via RequireJS as `vendor/gina/psl`. Shrinks the published tarball by ~780 KB and removes the only copyleft-flagged content from Socket's scan.
+### Removed
+* Removed orphaned core/deps/optimist-0.6.1/ vendored dependency. optimist (X11 license, flagged by Socket) was vendored but never actually used by any framework code — bin/cli parses CLI arguments directly via process.argv. Its declared transitives (wordwrap, minimist) were never installed, so any attempt to require it would have thrown MODULE_NOT_FOUND. Removal shrinks the published tarball by ~140KB and ticks up Socket's License score.
+
+## 0.3.7-alpha.2 - 2026-04-22 (npm only — no git tag)
+### Added
+* Inspector reveal toggle — dev-mode `/_gina/reveal` JSON endpoint returns the unredacted `__ginaData` snapshot when the bundle scope is `local`; bundles running in beta/production/testing return 403 and never store a raw snapshot. The Inspector Data tab has a matching red-tinted Reveal toggle that calls the endpoint and replaces the redacted payload client-side. Persisted in `localStorage.__gina_inspector_reveal`; automatically disabled and cleared when the bundle scope flips away from local.
+* Explicit exports for `gna.js` globals (#M8 / #AI3) — every framework-injected helper is now also surfaced as a named property on `require('gina')` / `require('gina/gna')`. Context helpers (`setContext`, `getContext`, `joinContext`, `resetContext`, `getLib`, `whisper`, `define`, `getDefined`, `isWin32`), path helpers (`_`, `setPath`, `getPath`, `setPaths`, `getPaths`, `onCompleteCall`), model helpers (`getModel`, `getModelEntity`), JSON/Data/Text/Console/Task helpers (`requireJSON`, `encodeRFC5987ValueChars`, `formatDataFromString`, `__`, `log`, `run`) and env helpers (`getUserHome`, `getEnvVar`, `getEnvVars`, `setEnvVar`, `getProtected`, `filterArgs`, `getLogDir`, `getRunDir`, `getTmpDir`, `getBundleStartingArgv`, `getVendorsConfig`, `setVendorsConfig`, `defineDefault`, `parseTimeout`, `merge`) plus `ApiError` are now statically discoverable, with JSDoc on each entry so IDEs, static analysers and the upcoming `.d.ts` generator (#M9) can navigate to definitions. Runtime globals are unchanged — this is an additive export surface only.
+* Auto-generated `types/gna.d.ts` from JSDoc (#M9) — new `script/generate_gna_types.js` reads the `GLOBAL_EXPORTS` inventory from `framework/v*/test/unit/gna-exports.test.js` (locked in by #M8) and per-export JSDoc blocks on `framework/v*/core/gna.js`, then emits `types/gna.d.ts`. For each global it prefers `typeof globalThis.<name>` when declared in `types/globals.d.ts`, otherwise synthesizes a TypeScript function signature from `@param`/`@returns`. Zero non-core dependencies. Wired into two new npm scripts — `npm run types:gen` (regenerate) and `npm run types:check` (CI-style drift detection, exit code 1 on mismatch). A new unit test `framework/v*/test/unit/gna-types-drift.test.js` re-runs the generator in-memory and asserts the output matches the checked-in file, so `.d.ts` drift is caught on every test run. Side effect — the regenerated file now covers the 12 exports that the hand-written `gna.d.ts` was missing (`joinContext`, `encodeRFC5987ValueChars`, `formatDataFromString`, `__`, `log`, `getProtected`, `filterArgs`, `getBundleStartingArgv`, `getVendorsConfig`, `setVendorsConfig`, `defineDefault`, `merge`), closing the #M8 → #M9 loop.
+* `gina bundle:mcp <bundle> @<project>` — generates a Model Context Protocol (MCP) tool manifest from `routing.json` at `<bundle>/config/mcp.json` (override with `--output=<path>`). Targets MCP specification revision 2025-06-18: emits one Tool per (route × URL variant × HTTP method) combination with `name`, `title`, `description`, `inputSchema` (Draft-07, `type: "object"`, URL path params as required strings with `pattern`/`enum` from `requirements`), `annotations` (`readOnlyHint` for GET, `destructiveHint` for POST/PUT/DELETE), and `_meta` (`io.gina.*` prefix preserving `routeName`, `url`, `method`, `namespace`, `control`, `middleware`, `scopes`, `cache`, `bundle`, `hostname`, `requirements`, `_sample` for downstream dispatch). Framework-internal routes (`/_gina/*`), HEAD, and OPTIONS are skipped. Cross-bundle proxy routes outside the current emission are warned and skipped. Source-of-truth is `routing.json` directly — independent of `bundle:openapi`. No alias. No runtime MCP server is started (deferred to #AI8b). Ships alongside a new `lib/routing-introspect/` module that extracts the shared URL/method/requirement parsing used by both `bundle:openapi` and `bundle:mcp`, covered by 45 unit tests in `test/lib/routing-introspect.test.js`. #AI8
+* `gina bundle:mcp-start <bundle> @<project>` — runs a live Model Context Protocol server for a single bundle over stdio (MCP specification revision 2025-06-18, JSON-RPC 2.0 framing, newline-delimited UTF-8). Reads the static manifest written by `gina bundle:mcp` from `<bundle>/config/mcp.json` and dispatches incoming `tools/call` requests as real HTTP requests against the running bundle's configured port on localhost. Implements `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/initialized`, and `notifications/cancelled`; unknown methods return `-32601` (METHOD_NOT_FOUND); argument validation failures return `-32602` (INVALID_PARAMS); tool execution failures (upstream 4xx/5xx, ECONNREFUSED, timeout) are returned as `{content, isError: true}` per MCP — never as JSON-RPC errors. Tool path parameters are substituted into the URL (`/invoice/:id` → `/invoice/42`); remaining arguments become the query string for GET/DELETE/HEAD or the JSON body for POST/PUT/PATCH. `application/json` and `application/problem+json` responses become `structuredContent` + a text block; non-JSON responses fall back to a text block. Default dispatch timeout is 30 seconds. Stdio discipline is enforced by an early intercept in `bin/cli`: when `bundle:mcp-start` is detected in argv, `process.stdout.write` is redirected to stderr and the real write is stashed on `process.__ginaMcpStdout` before any framework module is loaded — the MCP wire stays clean; framework logs, bootstrap noise, and `console.log` output go to stderr where MCP clients ignore them. The server warns on stderr if `routing.json` has been modified after `mcp.json` (stale manifest) and flags tools whose middleware list looks session-scoped (`auth`/`session`/`login`). Prerequisites — the bundle MUST be started (`gina bundle:start`) and a manifest generated (`gina bundle:mcp`) first. Ships with two new framework libraries — `lib/mcp-server/` (transport-agnostic JSON-RPC + lifecycle state machine) and `lib/mcp-dispatch/` (HTTP loopback dispatcher), covered by 80 unit tests across `test/lib/mcp-server.test.js`, `test/lib/mcp-dispatch.test.js`, and `test/bin/bundle-mcp-start.test.js`. #AI8 Phase 2a — Streamable HTTP transport deferred to a later phase.
+* `lib/mcp-dispatch` — concurrency cap on the HTTP loopback dispatcher. `createDispatcher({ maxInFlight })` rejects the (N+1)th concurrent `dispatch()` call with `{content, isError: true}` (never a JSON-RPC error) once the in-flight count reaches the cap; defaults to `DEFAULT_MAX_IN_FLIGHT = 16`. Early-exit paths (missing `_meta["io.gina.url"]`, unresolved path parameter, over-limit) do not consume a slot — only calls that actually issue an upstream HTTP request count against the budget. A new `getInFlightCount()` method is exposed on the dispatcher for ops instrumentation. Latent today in `bundle:mcp-start` because stdio is single-client; prevents pile-up behind a slow upstream once multiple MCP clients share one dispatcher via the Streamable HTTP transport (#AI8 Phase 2b).
+* `gina bundle:mcp-start --timeout-ms=<n>` — overrides the HTTP dispatch timeout for a single MCP server process. Also reads `mcp.json > server > timeoutMs` when the CLI flag is absent. Precedence: `--timeout-ms` > manifest > 30 000 ms default. Non-numeric / non-positive values at any layer fall through to the next layer with a stderr warning, so a malformed override cannot silently disable the timeout. The resolved value is surfaced in the startup info line (`Dispatch target: <url> (timeout: <n> ms)`) for operator visibility. The previous hardcoded 30 s default still applies when neither override is set.
+* Dual-mode Inspector statusbar link — the dev-mode statusbar now prefers the standalone Inspector SPA when `config/settings.json > inspector.url` is set on a bundle (e.g. `"inspector": {"url": "http://localhost:4200/inspector/"}`), opening it in a new tab with `?target=<this-origin+webroot>` pre-filled. When unset, the link falls back to the legacy embedded popup at `{webroot}/_gina/inspector/` with its persisted geometry — existing behaviour is unchanged. The resolved URL is exposed to the client shim via `window.__ginaData.gina.inspectorUrl`, injected by both `controller.render-swig.js` and `controller.render-json.js` so HTML and XHR-driven pages agree on the target. Cross-origin support for the standalone SPA is rounded out by adding `access-control-allow-origin: *` to the two remaining `/_gina/*` handlers that still lacked it — the Inspector SPA asset route (`/_gina/inspector/*`) and the log stream (`/_gina/logs`) — in both `server.isaac.js` and `server.js` so the SPA can pull CSS/JS/fonts and subscribe to the SSE logs from a different origin than the target bundle.
+* Dual-mode resolution for `gina inspector:open` — the command now picks the Inspector URL the same way the dev-mode statusbar does since `0.3.7-alpha.2`. Resolution order: (1) `--url=<url>` CLI override, (2) the bundle's `config/settings.json > inspector.url` (e.g. `"inspector": {"url": "http://localhost:4200/inspector/"}`), (3) the embedded popup at `<target>/_gina/inspector/` (legacy fallback, unchanged). In every case the target bundle origin is passed as `?target=<origin>` so the standalone SPA knows which bundle to drive. The `--url` flag is the escape hatch when the Inspector is reachable at an address not declared in the bundle config. When `--port` is used alone (no project/bundle context) and `--url` is not passed, the embedded path is kept — there is no config to read.
+* `gina inspector:open` now accepts a full `http(s)://` URL as the positional target — useful when bundles run on Docker or a remote environment while the Inspector SPA runs on the host (e.g. `gina inspector:open https://v3-local.example.com/api/`). The URL is used as the target origin directly; project and bundle resolution are skipped, mirroring the `--port` short-circuit. A new per-user fallback was also added to the Inspector URL resolution chain: `~/.gina/<shortVersion>/settings.json > inspector.url`. Set it once and every invocation without `--url=` uses the same standalone SPA origin. Full resolution order: (1) `--url=<url>`, (2) bundle `config/settings.json > inspector.url`, (3) global `~/.gina/<shortVersion>/settings.json > inspector.url`, (4) embedded popup at `<target>/_gina/inspector/`.
+* `gina service:list` — lists framework-internal services (bundles registered under `@gina`) with their name, preferred dev port, src-existence status, and current running state. Running state is probed from `~/.gina/run/<service>@gina.pid` combined with `process.kill(pid, 0)`; stale pidfiles report the service as stopped without being auto-deleted (clean-up stays with `bundle:stop`). Ports are read from `~/.gina/ports.reverse.json` and the preferred one picked by the `http/2.0 https` → `http/1.1 https` → `http/1.1 http` precedence (dev env first, then the first env present). Supports `--format=json` for scripting, and tolerates a missing or malformed `ports.reverse.json` without erroring. `@gina` is the only project accepted for now — `gina service:list @freelancer` is rejected with a clear message; user-defined services are not a surface yet. Ships with a new cmd group at `framework/v*/lib/cmd/service/` (`list.js`, `help.js`, `help.txt`) registered in the `bin/cli` offline allowlist, and 37 source-inspection unit tests in `test/lib/service-list.test.js`.
+* `gina connector:list` — lists connectors declared across a project's `shared/config/connectors.json` and every bundle's `config/connectors.json`, with driver install status, range and version-pin info. Three invocation modes: `gina connector:list` (every registered project), `gina connector:list @<project>` (one project, shared + all bundles), `gina connector:list <bundle> @<project>` (merged shared+bundle view that the bundle sees at runtime). Each row shows a status flag (`[ ok ]` installed or Node-builtin, `[ ?! ]` driver declared but not found in `<project>/node_modules/<driver>`, `[ ?? ]` unknown connector type or unrecognised `ai` protocol), the logical name, the resolved connector type, a source label (`[shared]`, `[<bundle>]`, `[<bundle> override]`), and driver details (`<npm>@<range>` + pin + installed version, or `run npm install <npm>` when missing, or `(built-in)` for `node:sqlite`). Driver resolution follows the framework's `peerDependencies`: `couchbase` → `couchbase`, `redis` → `ioredis`, `mysql` → `mysql2`, `postgresql` → `pg`, `mongodb` → `mongodb`, `scylladb` → `@scylladb/scylla-driver`, `sqlite` → built-in `node:sqlite`, `ai` → `@anthropic-ai/sdk` (for `anthropic://`) or `openai` (for `openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `together://`, `ollama://`, `gemini://`, `xai://`, `perplexity://`). Shared and bundle-level overlay is key-level with bundle winning on conflicting keys, mirroring the runtime merge in `core/config.js`. When two bundles pin the same driver at different `version` values the command emits a trailing `[ !! ] driver \`<name>\` has conflicting \`version\` pins` line — npm resolves `node_modules/<driver>/` to a single version per project, so the first install wins. Supports `--format=json` for scripting with a stable `{project, bundle?, status, connectors: [{project, bundle, name, connector, source, driver, builtin, range, version, installed, installedVersion, note, unresolved}]}` shape. `connectors.json` and `manifest.json` files are parsed with `//` and `/* */` comment tolerance via `requireJSON`. Registered as an offline command — no framework socket required. Ships with a new cmd group at `framework/v*/lib/cmd/connector/` (`list.js`, `help.js`, `help.txt`, `arguments.json`) and 89 source-inspection unit tests in `test/lib/connector-list.test.js`. First of the #CN10 multi-session plan — subsequent sessions add `connector:add`, `connector:rm`, and `connector:migrate`.
+* `gina connector:add` — writes a connector entry to a project's `shared/config/connectors.json` or a bundle's `<bundle-src>/config/connectors.json`. Two invocation modes: `gina connector:add <name> @<project>` (writes to shared) and `gina connector:add <name> <bundle> @<project>` (writes to the bundle, resolved via `manifest.bundles[bundle].src`). Connector type is inferred from `<name>` when it matches one of the six allowed types (`couchbase`, `mysql`, `postgresql`, `sqlite`, `redis`, `ai`), or set explicitly via `--connector=<type>` (or the `--driver=<type>` synonym). Flags cover the common keys: `--host=`, `--connector-port=`, `--database=`, `--username=`, `--password=`, `--scope=` (one of `local`, `beta`, `production`, `testing`), and the AI-specific `--protocol=`, `--model=`, `--api-key=`, `--base-url=`. Driver version pinning via `--driver-version=<range>` writes a `version` field on the entry (new in the `schema/connectors.json`); when set, the printed install hint uses the pin (`npm install ioredis@"^5.0.0"`) instead of the framework's `peerDependencies` range. Preserves any `//` or `/* */` comment header above the first `{`; serialises the body with 4-space indentation; pins `$schema` at the top of the output with the canonical `https://gina.io/schema/connectors.json` URL; preserves existing key order and replaces an overwrite in place (not moved to the bottom). After writing, prints a one-line install hint — `Next: run `npm install <pkg>@"<range>"` inside your project root.` — using `@anthropic-ai/sdk` for `anthropic://` or `openai` for any other OpenAI-compatible AI protocol (`openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `together://`, `ollama://`, `gemini://`, `xai://`, `perplexity://`). `sqlite` short-circuits to a `No install needed (Node >= 22.5.0 built-in node:sqlite)` note. Refuses to overwrite an existing entry without `--force`. Note on reserved flag names: the CLI uses `--connector-port=` (not `--port=`) because the framework reserves `--port=` for its own socket port, and `--driver-version=` (not `--version=`) because `--version=<value>` would be auto-mapped to `GINA_VERSION` and trigger a framework migration; the written JSON shape still uses `port` and `version` property names. Registered as an offline command — no framework socket required. Ships with 94 source-inspection unit tests in `test/lib/connector-add.test.js`. Second of the #CN10 multi-session plan — follow-ups are `connector:rm` and `connector:migrate` + framework-side auto-migrate hook.
+* `gina connector:rm` — removes a connector entry from a project's `shared/config/connectors.json` or a bundle's `<bundle-src>/config/connectors.json`. Two invocation modes mirror `connector:add`: `gina connector:rm <name> @<project>` (removes from shared) and `gina connector:rm <name> <bundle> @<project>` (removes from the bundle, resolved via `manifest.bundles[bundle].src`). `connector:remove` is accepted as an alias. Flags: `--dry-run` prints what would be removed without touching any file (always exits `0` — includes the sibling-usage warning and driver-retention hint); `--force` skips the project-level usage guard that otherwise refuses to remove a shared connector while any bundle still references it. Bundle-level removals always proceed and leave shared untouched. After removal, prints a driver-retention hint listing any sibling bundles (or shared) that still reference the same driver and a reminder that `gina does not uninstall npm packages`; sqlite is exempt (built-in `node:sqlite`). Attempting to remove from a bundle when the entry lives only in shared prints an "inherited from shared" hint pointing at the right scope. Preserves any `//` or `/* */` comment header above the first `{`; mid-body comments are lost on rewrite (same as `connector:add`). Registered as an offline command — no framework socket required. Ships with 81 source-inspection unit tests in `test/lib/connector-rm.test.js`. Third of the #CN10 multi-session plan — follow-up is `connector:migrate` + framework-side auto-migrate hook.
+* `gina connector:migrate` — lints every `connectors.json` in a project (or a single bundle's file) and, when `--fix` is passed, applies auto-fixable issues in place. Default mode is a read-only dry run — nothing is written without `--fix`. Two detection types today: `missing-schema` (top-level `$schema` key absent — auto-fixable, injects `"$schema": "https://gina.io/schema/connectors.json"` pinned at the top of the object while preserving the leading comment header and existing key order) and `bare-key-no-connector` (entry has no `connector` field and its key is not in the built-in enum `couchbase, mysql, postgresql, sqlite, redis, ai` — warn-only since the correct driver cannot be inferred; suggests the manual remediation via `gina connector:add <name> @<project> --connector=<type> --force`). Two invocation modes: `gina connector:migrate @<project>` scans shared + every bundle listed in `manifest.json`; `gina connector:migrate <bundle> @<project>` scans just the bundle's file. Flags: `--fix` applies auto-fixable issues; `--format=json` emits a machine-readable report with `{project, scope, bundle, fixApplied, files[]}` for CI / scripting. Registered as an offline command — no framework socket required. Idempotent — re-running after `--fix` is a clean no-op. Never modifies `core/config.js` and never runs at bundle boot: `connector:migrate` is explicit and opt-in, so a stale connectors.json cannot silently mutate in production. The real framework-side auto-migrate hook is deferred until `0.4.0` alongside `#CN8` (Couchbase SDK v2 removal) when a concrete old-shape → new-shape delta will justify touching the boot path. Ships with 87 source-inspection unit tests in `test/lib/connector-migrate.test.js`, a full write-path smoke test on a disposable sandbox (shared + two bundles, before/after assertions on `$schema` injection and key-order preservation), and a no-false-positive smoke on a real 7-bundle project. Fourth and final CLI session of the `#CN10` multi-session plan — `list`, `add`, `rm`, `migrate` now form a complete `connector:*` group.
+* `gina connector:add --install` — opt-in flag that runs the detected package manager's install command immediately after writing the connector entry. The package manager is detected by probing the project root for lockfiles in order: `bun.lockb` → `pnpm-lock.yaml` → `yarn.lock` → `package-lock.json`. npm is the fallback when none matches. The install range is resolved in three tiers, first match wins: (1) `--driver-version=` pin set on the call (also persisted under `entry.version`); (2) the project's `package.json` (`dependencies` preferred over `devDependencies`) — reusing an already-declared range keeps the lockfile stable across repeated installs; (3) the framework's `peerDependencies` declaration. The resolved tier is labelled in the pre-install log (`(source: entry | project | framework)`) so the decision is visible in the terminal. `sqlite` short-circuits to exit 0 with a "built-in, no install needed" note. AI connectors with missing or unknown `protocol` exit 1 (the entry is still persisted to disk so the user can fix the protocol and re-run `--install` separately, or install by hand). Spawn uses `child_process.spawnSync` with `stdio: 'inherit'` so the PM's native output streams through to the user's terminal; `ENOENT` (PM binary missing from PATH) returns exit code 127. By design there is no `--no-install` / `--yes` counterpart and no configuration that silently flips the default — `--install` is opt-in and locked by a negative-invariant source-inspection test. No changes to `core/config.js` or any framework boot path. Ships with 40 new source-inspection unit tests in `test/lib/connector-add.test.js` (135/135 pass; full connector suite 392/392) and a live smoke covering sqlite short-circuit, AI unknown-protocol exit 1, real `ioredis` install via npm fallback, subsequent install via lockfile-detected npm with a project-pinned range, and `--driver-version=^5.3.0` taking priority. Fifth and final CLI session of the `#CN10` multi-session plan — `list`, `add` (with `--install`), `rm`, `migrate` now form the complete `connector:*` group.
+* `lib/mcp-http` — Streamable HTTP transport primitives for the MCP server (spec revision 2025-06-18). New framework library that wraps an `mcp-server` instance with `createHttpTransport({ mcpServer, host, port, maxBodyBytes, onError })` — binds an `http.createServer` on the configured host / port (defaults to `127.0.0.1:0`, OS-assigned) and exposes `.start() / .stop() / .address()` for lifecycle control. POST accepts either a single JSON-RPC 2.0 frame or a batch (array); the `Accept` header picks the response shape — `application/json` returns a JSON frame (or JSON array for batch), `text/event-stream` returns one `event: message` per non-notification frame and closes the stream. Notifications-only POSTs return 202 Accepted with an empty body. Body size is capped at `DEFAULT_MAX_BODY_BYTES = 1 MiB` (override via `maxBodyBytes`); overflow replies 413 + JSON-RPC error frame. GET and DELETE return 405 + `Allow: POST` — v1 has no server-initiated streams (`tools/list_changed: false`, no sampling, no roots) so the spec-compliant answer is to refuse the method. OPTIONS returns a minimal preflight (full CORS Origin echo and `--auth-token` enforcement land in #AI8 Phase 2b Session 2). `Mcp-Session-Id` is generated via `crypto.randomUUID()` on the `initialize` response when the client did not provide one; client-supplied ids are echoed on every response including 202. `.stop()` sets `keepAliveTimeout = 1` and calls `closeIdleConnections()` so SIGTERM-driven shutdowns don't stall on idle keep-alive sockets. 34 unit tests in `test/lib/mcp-http.test.js`. Registered in the lib registry as `lib.mcpHttp` — not yet wired to `bundle:mcp-start`; the `--transport=http` CLI surface lands in #AI8 Phase 2b Session 3.
+* `lib/mcp-http` — security layer on the MCP Streamable HTTP transport. Two new options on `createHttpTransport`: `authToken` (enables static bearer authentication — requests must carry `Authorization: Bearer <token>` on every non-OPTIONS request) and `allowedOrigins` (extends the built-in loopback `Origin` allowlist; pass `["*"]` to disable the check entirely). The built-in allowlist accepts `http(s)://localhost`, `http(s)://127.0.0.1`, and `http(s)://[::1]` on any port so MCP Inspector and browser dev tools on random dev ports work without extra configuration. Ordering is OPTIONS → Origin gate → bearer gate → method routing: preflight bypasses auth (browsers cannot carry `Authorization` on a preflight), a disallowed `Origin` returns 403 without CORS echo (self-defeating otherwise), and a missing / invalid bearer returns 401 + `WWW-Authenticate: Bearer realm="MCP"` with CORS headers preserved so browser clients can read the error body. Bearer validation uses `crypto.timingSafeEqual` with a length-mismatch short-circuit (timingSafeEqual throws on unequal lengths), and the scheme prefix is parsed case-insensitively per RFC 6750 with trailing-whitespace tolerance on the presented token. Response CORS headers (`access-control-allow-origin` + `vary: Origin`, or `*` with no `vary` under wildcard) are now echoed on every POST / 202 / 405 / 413 / 500 path when the request carried an allowed Origin. OPTIONS preflight now lists `authorization` in `access-control-allow-headers` and honours the same Origin allowlist (allowed origin → echoed; disallowed → 204 with no `access-control-allow-origin`, so the browser blocks the actual request). 36 new unit tests cover the Origin allowlist (default loopback, IPv6 `[::1]`, extra origins, `*` wildcard, non-http schemes, malformed URLs), the bearer flow (missing / wrong scheme / wrong value / length-mismatch / trailing whitespace / case-insensitive scheme), CORS echo on every response path, OPTIONS preflight behaviour under each Origin policy, and input validation (empty / non-string `authToken` → no auth; non-array `allowedOrigins` → loopback-only default). Still not wired to `bundle:mcp-start` — CLI surface lands in #AI8 Phase 2b Session 3.
+* `gina bundle:mcp-start --transport=http` — Streamable HTTP transport for the live MCP server (MCP spec revision 2025-06-18). The existing stdio behaviour is preserved as the default; passing `--transport=http` wires the same dispatcher + mcp-server instance to `lib/mcp-http.createHttpTransport()` instead of `attachStdio()`. Six new CLI flags are whitelisted in `lib/cmd/bundle/arguments.json`: `--transport=stdio|http`, `--http-host=<host>`, `--http-port=<n>`, `--max-in-flight=<n>`, `--auth-token=<token>`, `--cors-origin=<comma-list>`. Every flag has a matching `mcp.json > server > <field>` manifest fallback (`transport`, `httpHost`, `httpPort`, `maxInFlight`, `authToken`, `allowedOrigins`) and, where sensible, an env-var layer (`GINA_HOST_V4` for the bind host, `GINA_MCP_AUTH_TOKEN` for the bearer token). Precedence at every resolver: CLI → manifest → env → default, with invalid values (non-numeric port, negative max-in-flight, out-of-range integer, unknown transport name) warning on stderr and falling through to the next tier. Bind host defaults to the framework-wide `host_v4` loopback convention (`127.0.0.1` by default, same mechanism as the MQ listener and CLI daemon socket) — opt into `0.0.0.0` is deliberate. HTTP port defaults to `0` (OS-assigned); the resolved port is logged to stderr on startup so wrappers can discover it. The startup info line now reads "MCP server listening on http://<host>:<port> (bearer auth: enabled)?. Dispatch target: <baseUrl> (timeout: <n> ms, maxInFlight: <n>). <N> tools exposed." On SIGTERM / SIGINT, `gracefulExit()` awaits `httpTransport.stop()` before `process.exit()` so in-flight responses drain cleanly. The `bin/cli` stdout intercept from Phase 2a is a no-op under HTTP mode (nothing writes to stdout in that path) and is therefore preserved unchanged. 27 new source-inspection tests in `test/bin/bundle-mcp-start.test.js` cover the whitelist additions, each resolver's precedence chain, the stdio|http branch in `startServer`, the HTTP transport wire-up shape, the bearer-auth log annotation, and the SIGTERM / `httpTransport.stop()` drain. `bundle:mcp-start` help.txt extended with the new flag table and default-security-posture notes. #AI8 Phase 2b Session 3.
+* `swig.useProject` — opt-in `config/settings.json` key that loads a project-pinned `@rhinostone/swig` (or `@rhinostone/swig-twig`) from the project's `node_modules/` in place of the framework's bundled copy. The override is honoured only when the project pin shares the same major as the framework floor and is at or above it (currently `^1.6.0`); a rejected override falls back to the framework copy and logs a one-line `[swig-resolver]` warning at bundle startup naming the reason (`version-mismatch`, `not-installed`, `malformed-package-json`, `missing-version`). Default is `false` — existing bundles see no behaviour change. A second key `swig.package` (enum `@rhinostone/swig` | `@rhinostone/swig-twig`, default `@rhinostone/swig`) selects which frontend package to resolve; the abandoned upstream `swig` name is never accepted. The resolved module is cached on `process.gina._swig` for the life of the bundle process, so `core/server.js` and `core/controller/controller.js` both see the same instance — including after dev-mode `refreshCoreDependencies()` evictions. Ships with `lib/swig-resolver/` (`resolve`, `load`, `get`, `getDecision`, `reset`) and 51 unit tests in `test/lib/swig-resolver.test.js`. Schema updated in `schema/settings.json`. Standalone-mode note: when multiple bundles share a process, the first one to call `load()` wins; a subsequent bundle requesting a different package is warned and keeps the already-loaded copy.
+* `lib/nunjucks-resolver` — primitive (N1) for project-installed nunjucks detection. Mirrors the `lib/swig-resolver` shape (resolve / load / get / getDecision / reset + dev-mode mtime hot-swap via `process.gina._nunjucks*`) with two deliberate differences: (1) no framework-bundled fallback — nunjucks is never declared in `framework/v*/package.json`, so `load()` throws an `Error` with `code: NUNJUCKS_NOT_INSTALLED` when the project has not installed the package, instead of silently returning a framework copy (bundles fail loud at startup rather than mid-render); (2) no version floor — the framework itself never calls any nunjucks API (rendering will live in `controller.render-nunjucks.js`, Gina code), so any version the user installs is accepted. Same dev-mode hot-swap mechanism: when `NODE_ENV_IS_DEV=true`, each `get()` call `fs.statSync`-probes `<projectPath>/node_modules/nunjucks/package.json` and, on mtime drift, evicts the cached module from `require.cache` and re-runs `load()` with the stashed options — `npm install nunjucks@<newer>` in a dev project takes effect on the next request without a bundle restart. Production short-circuits the probe. Ships with 38 unit tests in `test/lib/nunjucks-resolver.test.js` — resolve paths (installed / not-installed / malformed / missing-version / package-override), load success + cache + idempotency, load rejection with structured error + decision attached, get() throw-before-load contract, reset() fields, dev-mode mtime hot-swap including the uninstall-between-loads case that surfaces the error on refresh. Registered in `lib/index.js` as `lib.nunjucksResolver`. No wiring into `server.js` / `controller.js` yet — that lands in N2 alongside `controller.render-nunjucks.js` and the `render.engine` settings key.
+* `settings.json > render.engine = "nunjucks"` — opt-in nunjucks rendering for a bundle (N2 MVP). New `core/controller/controller.render-nunjucks.js` delegate file, mirroring `render-swig.js`'s module signature (`async function(userData, displayInspector, errOptions, deps)`). `controller.js` `self.render()` now reads `settings.render.engine` from the bundle config and dispatches to either `controller.render-swig` (default) or `controller.render-nunjucks`. The dev-mode cacheless branch evicts the nunjucks delegate from `require.cache` alongside the existing swig / v1 entries, wrapped in try/catch so older framework dirs without the nunjucks delegate still load. `server.js` gains a new `initNunjucksEngine(conf)` helper called alongside `initSwigEngine` when `hasViews(bundle)` is true — for bundles with `render.engine === "nunjucks"`, it calls `lib.nunjucksResolver.load(self.executionPath, settings.nunjucks)`, which throws `NUNJUCKS_NOT_INSTALLED` when the project has not `npm install`ed the package (bundle startup fails loud rather than deferring the error to the first render). `render-nunjucks.js` caches a `nunjucks.Environment` per template root on `process.gina._nunjucksEnvs` (invalidated when the underlying nunjucks module itself was hot-swapped via `process.gina._nunjucksEnvsOwner`), disables nunjucks's own template cache in dev mode (`noCache: process.env.NODE_ENV_IS_DEV === "true"`) so template edits take effect without restart, and wires the namespace-aware template path resolution from `render-swig.js:271-335` (the CVE-2023-25345 path-traversal guard is swig-specific legacy and remains in `render-swig.js` only). HEAD requests send headers only; HTTP/1.1 uses `res.writeHead() + res.end()`. Schema updates in `schema/settings.json`: new top-level `render` block (`engine` enum `["swig","nunjucks"]`, default `"swig"`) and `nunjucks` block (`package`, `autoescape`). **Explicitly deferred to follow-up sessions** — documented in `render-nunjucks.js`'s header comment so nothing is hidden: (1) Inspector `__gdPayload` injection, (2) HTTP/2 `stream.respond()` direct path and Early Hints 103, (3) static HTML cache writes, (4) `setResources` asset injection and `<gina>` layout placeholder resolution, (5) Gina `SwigFilters` equivalents — users register their own filters via `nunjucks.Environment.addFilter()`, (6) error-page template routing (the framework error template is currently swig-only, so thrown errors from nunjucks pages still render via the swig path). 36 source-inspection unit tests in `test/lib/render-engine-dispatch.test.js` — schema shape, controller.js dispatch logic, cacheless eviction try/catch, render-nunjucks module shape, Environment cache invalidation, HEAD handling, deferred-features comment presence, server.js init wiring, and negative invariants (framework `package.json` must never declare nunjucks; `render-nunjucks.js` must never `require("nunjucks")` directly; dispatch default must stay `"swig"`). Full suite 3273/3273.
+* `script/check_changie_entries.js` + pre-commit hook — self-enforces `llms.txt` lesson #66 (changie YAML body shapes). The script validates every staged `.changes/unreleased/*.yaml` entry: `kind:` must match the Added/Changed/Deprecated/Removed/Fixed/Security enum, `body:` must be single-quoted (`body: '...'`), double-quoted, or a block scalar (`>-` / `|-` / `>` / `|`), `time:` must be an ISO-8601 shape. Unquoted bodies are rejected unconditionally — even when today's content happens to be safe — because a later edit could introduce the ` #` silent-truncation or `:` mapping-values hazards. Single-quoted bodies are walked character-by-character to ensure every literal `'` is escaped as `''` and the scalar terminates before the `time:` key. Double-quoted bodies are checked for a closing unescaped `"`. Wired into `.githooks/pre-commit` alongside the existing local-tool-path leak guard (#S5) — runs only against staged changes files (`git diff --cached --diff-filter=AM`), so pre-existing unquoted entries on disk are grandfathered until someone edits them. The script is also callable standalone (`node script/check_changie_entries.js .changes/unreleased/*.yaml`) for CI use or on-demand audits. 25 unit tests in `test/lib/check-changie-entries.test.js` cover every safe body shape (single-quoted with escapes, double-quoted with escapes, folded `>-` and literal `|-` block scalars), all rejection patterns (unquoted with `:`, unquoted with ` #`, unquoted plain, unescaped `'` inside single-quoted, unterminated single-quoted, unterminated double-quoted), missing / empty / wrong-kind / wrong-field-order fields, and batch behaviour (every failing file reported in one pass; no-args → exit 0; missing-file-path → reported). Exits 1 with a per-file reason on any failure, exit 0 when clean. Full suite 3298/3298.
+### Changed
+* Inspector refresh button now performs a full soft refresh instead of only invalidating the data-diff cache. One click re-polls data, force-refetches the live index introspection (`/_gina/indexes`), refetches the unredacted `/_gina/reveal` snapshot when reveal mode is active, and reopens the passive `/_gina/agent` SSE stream when it has closed. Shift+click additionally reloads the inspected page via `window.opener.location.reload()`. The button's tooltip advertises the Shift+click modifier.
+* `gina bundle:list` — each bundle line now shows a preferred-port summary and host-side running state alongside the existing `[ ok ]` / `[ ?! ]` src-existence indicator. Preferred port is read from `~/.gina/ports.reverse.json` by the `http/2.0 https` → `http/1.1 https` → `http/1.1 http` precedence (dev env first, then the first env present); bundles with no allocated port render as `(no port)`. Running state is derived from `~/.gina/run/<bundle>@<project>.pid` + `process.kill(pid, 0)`; a stale pidfile (process gone) reports the bundle as stopped without deleting the file (clean-up stays with `bundle:stop`). Text output gains a padded bundle-name column, the port summary, and a `(running, pid N)` or `(stopped)` suffix per bundle; `--format=json` output gains `ports: object|null`, `running: boolean`, and `pid: number|null` fields on each bundle object. A missing or malformed `ports.reverse.json` is tolerated — the command still renders with all bundles showing `(no port)`. Caveat: bundles running inside a Docker container do not write a pidfile to the host `~/.gina/run/` directory, so they will report as stopped from a host shell even when the container is up — use `docker ps` for the container-side view.
+* `swig.useProject` — dev-mode hot-swap via mtime check. When `NODE_ENV_IS_DEV=true` and a bundle has opted in to `swig.useProject: true`, every call to `lib.swigResolver.get()` (which runs on every HTTP request via `controller.js` re-require under `refreshCoreDependencies()`) `fs.statSync`-probes the project's `<projectPath>/node_modules/<pkg>/package.json` and compares the `mtimeMs` against the value cached at the last `load()`. Identical → return the cached swig instance (near-zero cost: one `fs.stat`). Different (or the file appeared / disappeared) → evict the old project copy from `require.cache`, clear the in-process cache (`process.gina._swig` / `_swigDecision` / `_swigPackage`), and re-run `load()` with the original options so the next access picks up the new version. Use case: `npm install @rhinostone/swig@<newer>` in a project while a dev bundle is running now takes effect on the next request without a bundle restart. Production bundles (`NODE_ENV_IS_DEV` not `true`) short-circuit the mtime probe and keep the load-once semantics. Downgrades below the framework floor or wrong-major upgrades re-enter the same safety gates as the initial `load()` — the refreshed decision falls back to the framework copy with the usual `[swig-resolver]` warning. `reset()` now clears the full cache (adds `_swigOptions`, `_swigProjectPath`, `_swigMtime` to the fields wiped). 7 new unit tests in `test/lib/swig-resolver.test.js` (58 total) cover the production no-op, unchanged-mtime short-circuit, mtime-triggered reload, toggle-off and missing-projectPath short-circuits, fresh-get without prior `load()`, and version-drift-below-floor fallback. Test fixtures use a helper-local monotonic mtime counter (`Math.max(prev, Date.now(), lastMtime) + 1000`) to guarantee strict mtime progression across successive calls — `Date.now()` millisecond granularity would otherwise collide when two calls fire within the same wall-clock millisecond. `ROOT` is realpath-normalised inside `before()` because macOS `os.tmpdir()` returns `/var/folders/...` while Node's `require.cache` keys use the realpath `/private/var/folders/...`.
+* `controller.render-nunjucks.js` — Inspector `__gdPayload` injection shipped (closes N2 deferred item #1). `injectInspectorScripts(html, data, self, local, displayInspector)` builds the same redacted payload shape as `render-swig.js:1041-1128` (two `JSON.parse(JSON.stringify(data.page))` clones into `__gdGina` / `__gdUser`, `view.scripts`/`view.stylesheets` scrubbed on both, `inspectorRedact.getConfig(local.options.conf)` for pattern config, `environment.scope` + `inspectorUrl` attached to the gina clone, `JSON.parse(JSON.stringify(...))` snapshot gated on `process.env.NODE_SCOPE === 'local'` before the redact pass, then `inspectorRedact.redact({compiledPatterns, replacement})`), serialises to `<script>window.__ginaData = ...</script>` with `</script>` → `<\/script>` and `<!--` → `<\!--` escapes matching swig at lines 1096-1097, and injects alongside a `<script>window.__ginaLogs</script>` console-hook script before the first `</body>` via case-insensitive regex replace. Gated on `displayInspector === false` → never; `displayInspector === true` → always; otherwise `self.isCacheless()` (dev-mode default, same as swig). Side effects: stashes redacted payload on `self.serverInstance._lastGinaData` (consumed by engine.io push + `/_gina/agent` SSE), stashes unredacted on `serverInstance._lastGinaDataUnredacted` when scope is local (null otherwise so `/_gina/reveal` has nothing to leak outside dev), and emits `process.emit('inspector#data', __gdPayload)`. The injection call is wrapped in try/catch in the render function body so an Inspector-side bug can never break the actual page render — it falls through to sending the un-injected HTML with a `[render-nunjucks] inspector injection skipped: ...` console warning. **Still deferred within the Inspector port:** (a) `statusbar.html` inclusion (the swig template uses `{% include %}` with swig-specific syntax; nunjucks-compatible version needed), (b) `data.page.flow` pipeline from `local._timeline` (render-swig.js:986-1040 shape; belongs in a shared helper before porting), (c) `data.page.queries` pipeline from `local._queryLog`. 18 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05b — imports, helper declaration, both gates (`displayInspector` + `isCacheless`), `</body>` guard, payload construction, redact pipeline, unredacted-scope gate, `</script>`/`<!--` escapes, script tag text, console-hook script, serverInstance stashes, event emit, regex replace injection site, try/catch wrapping in the main render body, plus two "documentation" tests that lock in the within-Inspector deferred-features comment. Full suite 3316/3316. render-nunjucks.js header block updated to strike through the shipped deferred item and expand the remaining within-port deferred list.
+* `controller.render-nunjucks.js` — HTTP/2 `stream.respond()` direct path shipped (closes N2 deferred item #2). `sendHtmlResponse` now implements the four-way branch documented in `the internal architecture docs §7b` and used by `render-swig.js:877-927`: (1) HEAD + HTTP/2 stream → `stream.respond({content-type, content-length, :status, ...merged})` + `stream.end()` with no body; (2) HEAD + HTTP/1.1 → `res.setHeader(content-length)` + `res.writeHead()` + `res.end()`; (3) body + HTTP/2 stream → `stream.respond({content-type, :status, ...merged})` + `stream.end(html)`; (4) body + HTTP/1.1 → `res.writeHead()` + `res.end(html)`. Both HTTP/2 branches guard against `stream.destroyed || stream.closed` (client disconnected before the async render callback completed — without the guard, `stream.respond()` throws `ERR_HTTP2_INVALID_STREAM`). Both HTTP/2 branches merge pipeline-set headers via `local.res.getHeaders()` because `stream.respond()` on the raw HTTP/2 stream does NOT include headers set via `response.setHeader()` — CORS, cache-control, cookies set earlier in the pipeline would otherwise be silently dropped on HTTP/2 responses. `local.res.headersSent = true` is flagged after successful `stream.respond()` to signal the HTTP/1.1 compat layer that the response was sent directly. Still deferred within the HTTP/2 track: Early Hints 103 auto-send from accumulated `h2Links` — that fires in `controller.js this.render()` before the delegate is called, so it's a controller-level change rather than a render-nunjucks change. 10 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05a covering each of the four branches, the stream-destroyed guard (asserted to appear at least twice for both HEAD and body paths), the pipeline-header merge (getHeaders() called at least twice), the headersSent flag (set at least twice), and the HTTP/1.1 fallback patterns. Full suite 3326/3326.
+* `controller.render-nunjucks.js` — error-page template routing shipped (closes the remaining "framework error template is swig-only" gap for nunjucks bundles). When a bundle has opted into `render.engine = "nunjucks"` and defines custom error templates under `templates/html/errors/<code>.html`, `controller.js renderCustomError()` sets `errOptions.file` to the absolute path of the matching error file from `bundleConf.content.templates._common.errorFiles[code]`. The render-nunjucks delegate now detects `localOptions.isRenderingCustomError === true` and branches: instead of going through `resolveTemplatePath` + `FileSystemLoader.render()` (the loader rejects absolute paths and cannot reach shared-path error templates that live outside the bundle template root), it reads the file with `fs.readFileSync(localOptions.file, 'utf8')` and renders the contents with `env.renderString(source, data)`. Every failure mode in the branch — absent path, missing file, read error, renderString error — falls back to a minimal inline HTML body served through `sendHtmlResponse`, never recursing via `self.throwError`. Recursion would re-enter the same branch and could loop infinitely; the inline fallback guarantees the client always gets a well-formed response. Defensive `localOptions.isRenderingCustomError = false` reset after render mirrors `render-swig.js` lines 804 and 1434 — prevents a downstream render that reuses the same `localOptions` reference from re-entering the branch. The shared `getEnvironment(nunjucks, templateRoot, ...)` call is now hoisted above the branch so both the custom-error path (uses `env.renderString`) and the normal path (uses `env.render`) reuse the same cached `nunjucks.Environment`. 14 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05c — branch presence and ordering relative to `resolveTemplatePath`, `fs.readFileSync` on `localOptions.file`, `env.renderString(_errSource, data)` usage, missing-file fallback, read-error fallback, renderString-error fallback, the no-recursion negative invariant (`self.throwError` must never appear inside the branch body), flag reset after render, inline-HTML status-code derivation, `getEnvironment` ordering, normal-path regression guard (`env.render(templateRel, data)` still present), template-existence pre-flight guard, and the top-of-file header "shipped" lock. Full suite 3326 → 3340. Deferred-feature list in the render-nunjucks.js header block, `the internal architecture docs` §5 + §8, and `llms.txt` #67 all updated to mark the item as shipped.
+### Removed
+* Removed the unused vendored swig-client browser bundle (core/deps/swig-client/). The client-side Swig bundle is produced at build time from @rhinostone/swig (Phase 7) — the vendored copy had zero runtime or build-time references.
+### Fixed
+* Inspector payload redactor no longer false-positively redacts non-secret identifiers that happen to contain secret substrings (e.g. `companyName`, `lastCompanyUsedId`, `passportRequired`). The key matcher now tokenizes on camelCase and punctuation boundaries and compares anchored tokens, so only genuine secret-named fields are redacted.
+* Inspector Reveal toggle now reliably shows the full HTML page payload instead of tiny session data from background JSON polls. The unredacted snapshot is only written by HTML renders — JSON polling endpoints no longer clobber the slot between page load and click.
+* Inspector Reveal toggle now routes to the correct bundle in proxy-routed multi-bundle setups. `toggleReveal()` derives the `/_gina/reveal` URL from the opener window's pathname (or the standalone `?target=` param) so the request hits the bundle that rendered the current page, not the front proxy's default bundle.
+* Bundle startup no longer crashes with `EINVAL: invalid argument, readlink` when loading config files in dev mode. The `require.cache` eviction calls in `config.js` `loadWithTemplate` are now wrapped in try/catch — `requireJSON` reads config via `fs.readFileSync` and evicts its own cache, so filesystem races (observed on OrbStack/Docker bind mounts after the bundles symlink is re-created) are non-fatal.
+* Bundle no longer crashes with an uncaught `ECONNREFUSED` when an HTTP/2 client session fails to connect. The `client.on('error', ...)` listener in `handleHTTP2ClientRequest` had a property-access chain (`getContext('gina').ports[options.protocol][options.scheme.replace(...)][options.port]`) that threw `TypeError` when the caller passed a bare hostname (undefined `options.protocol`/`options.scheme`). A throw from inside an `'error'` listener becomes an `uncaughtException` and terminates the process. The whole listener body is now wrapped in try/catch, the port-enhancement lookup safe-navigates every key, and `proc.js` `uncaughtException` handler now filters `ECONNREFUSED` originating from TCP connect frames (matching the existing `ECONNRESET` behaviour).
+* Inspector tab content now refreshes automatically when the opener page navigates. The client-side log poller (`pollLogs` in `inspector.js`) tracked `logsOff` against the opener's `__ginaLogs` array but never detected that the array itself is replaced on navigation — the new page's `statusbar.html` inline script re-runs and installs a fresh empty array, so the old `logsOff` offset would be larger than the new array length and the guard `src.length <= logsOff` returned early forever. New `_lastLogsRef` holds the last-polled array reference; when it changes (or the array length shrinks below the offset), `logsOff` is reset to 0 so the new page's entries are picked up on the next poll cycle.
+* Detached daemon processes no longer spin at 100% CPU when their launching CLI exits and leaves an orphaned stdio pipe. Writing to the dead pipe triggered `EPIPE`, which escalated to `uncaughtException`; the existing handler then wrote the error back to the same dead stdout, producing another `EPIPE` — an infinite loop. `proc.js` now installs silent `error` listeners on `proc.stdout`/`proc.stderr` at init, guards the uncaughtException EPIPE branch with a re-entry flag, and wraps the diagnostic `stdout.write()` calls in `try/catch` so a subsequent write failure is swallowed instead of re-thrown.
+* `gina framework:init` now re-heals project fields that have been saved as `null` in `projects.json`. The integrity loop in `checkIfProjects` used `typeof(project[prop]) != 'undefined'` to decide whether a field needed refreshing from `main.json`; because `typeof null === 'object'`, a field that had been written as `null` in a previous run (for example because its per-release entry was not yet defined) was permanently skipped. The guard now also requires `project[prop] !== null`, so `def_scope`, `local_scope`, `production_scope`, `dev_env` and similar namespaced fields recover on the next framework start.
+* `gina bundle:start` no longer hangs indefinitely when the resolved bundle entry point does not exist on disk. The `isRealApp` callback in `lib/cmd/bundle/start.js` used to log the error via `terminal.error()` and then return without closing the CLI socket or calling `end()` — the connected `gina` CLI would wait forever for output that could not arrive. The error branch now mirrors the sibling `nodeModulesErr` path: `opt.msg` is set to the error message and `end(opt, cmd, isBulkStart, bundleIndex, true)` is called, so the CLI receives the error and the process exits cleanly.
+* Inspector popup now stays in sync during SPA (pushState/XHR) navigation inside the inspected page. Opener polling alone could not pick up SPA renders because those paths do not rewrite `window.__ginaData`. The Inspector now opens a parallel `/_gina/agent` SSE subscription alongside the existing opener source and receives pushed `data`/`log` frames from `render-json.js` whenever `process.gina._inspectorActive` is true. Multi-bundle proxy setups are handled by deriving the stream URL from the opener pathname. Manual refresh after each page change is no longer required.
+* `gina bundle:openapi` no longer crashes on `routing.json` files that contain `//` or `/* */` comments. The command used plain `require(routingPath)` which hands the file to Node's JSON loader, and that loader throws `SyntaxError` on any comment — including the `// bundle needs to be restarted on changes !!` header that real `routing.json` files routinely carry. Swapped to `requireJSON`, which strips comments before parsing. The new `bundle:mcp` command already used `requireJSON`; this aligns `bundle:openapi` with it.
+* `gina project:add @<name> --path=<dir>` no longer hangs indefinitely when the target directory already contains a `package.json`. The existing-file branch now merges the existing package with the framework template and exits cleanly.
+* CLI argument parsing no longer silently truncates `--<key>=<value>` flags whose value contains a literal `=` character. Both entry points in the argv pipeline — `utils/helper.js::filterArgs` (populates `process.gina.GINA_*`) and `lib/cmd/helper.js::getParams` (populates `cmd.params[<key>]`) — previously used `.split(/=/)` with no limit, chopping the value at every `=`. Real-world values affected: `--driver-version=">=5.3.0 <6.0.0"` (truncated to `>`), `--password=foo=bar` (truncated to `foo`), `--api-key=sk-=abc=` (truncated to `sk-`). Fix is an `indexOf('=')`-based substring that splits on the first `=` only; everything after is kept verbatim. Discovered during the `connector:add --install` smoke test (CN10 Session 5) when a semver range with a leading `>=` was silently chopped. Covered by 13 unit tests in `test/lib/cli-arg-parsing.test.js` (source-inspection on both sites + behavioural checks against `>=X.Y.Z`, caret ranges, multi-`=` passwords, base64-ish api keys, empty values, and flag-only tokens). Full suite 3044/3044.
+
 ## 0.3.6 - 2026-04-16
 ### Changed
 * syncDocs now regenerates the docs-site package-lock.json after bumping devDependencies.gina — prevents CI / Vercel / Worker deploy failures on every stable release.
@@ -15,10 +73,10 @@ and is generated by [Changie](https://github.com/miniscruff/changie).
 * Surfacing the real cause when `prepare_version.js` is run against a stale `~/.gina/<release>/settings.json` `dir` field. Publish now fails fast with an actionable message instead of wedging at `pushChangesToGitIfNeeded` with a misleading "No branch selected" error.
 * Preventing CORS preflight failure when a bundle's env.json `access-control-allow-headers` list omits a header the client actually sends. `completeHeaders()` no longer overwrites the echo that `checkPreflightRequest()` sets from the incoming `access-control-request-headers` (#B13).
 ### Security
-* Added pre-commit hook (.githooks/pre-commit) that blocks Claude-related paths (CLAUDE.md, .claude*) from entering git history. post_install.js installs core.hooksPath=.githooks for contributor clones only (gated on .git presence in gina repo root). #S5 follow-up to #S3.
-* Added GitHub Actions workflow (.github/workflows/security.yml) that greps the git index on every push/PR to develop and master for Claude-related paths (CLAUDE.md, .claude*). Fails the build if any are tracked. Backs up the local pre-commit hook (#S5) and publish-boundary gate (#S3). #S6 follow-up to #S3.
-* Added private-token leak gate (script/check_no_claude_leak.js) wired into the npm prepack hook and the prepare_version.js self.* chain before any git add --all. Fails the publish if the tarball listing contains Claude-related paths OR if pack contents contain private-token patterns (phone, private email, private address, private domain, co-author legal name). #G1 follow-up to #S3/#S4.
-* Added opt-in pre-commit hook (resources/git-hooks/pre-commit) that blocks commits authored under a private-domain git identity (.local hostnames, internal domains). Contributors install it once via cp resources/git-hooks/pre-commit .git/hooks/pre-commit. Complements the CI-side Claude-path guard (#S5/#S6). #G5.
+* Added pre-commit hook (.githooks/pre-commit) that blocks local-tool configuration paths from entering git history. post_install.js installs core.hooksPath=.githooks for contributor clones only (gated on .git presence in gina repo root). #S5 follow-up to #S3.
+* Added GitHub Actions workflow (.github/workflows/security.yml) that greps the git index on every push/PR to develop and master for local-tool configuration paths. Fails the build if any are tracked. Backs up the local pre-commit hook (#S5) and publish-boundary gate (#S3). #S6 follow-up to #S3.
+* Added private-token leak gate (script/check_no_local_leak.js) wired into the npm prepack hook and the prepare_version.js self.* chain before any git add --all. Fails the publish if the tarball listing contains local-tool configuration paths OR if pack contents contain private-token patterns (phone, private email, private address, private domain, co-author legal name). #G1 follow-up to #S3/#S4.
+* Added opt-in pre-commit hook (resources/git-hooks/pre-commit) that blocks commits authored under a private-domain git identity (.local hostnames, internal domains). Contributors install it once via cp resources/git-hooks/pre-commit .git/hooks/pre-commit. Complements the CI-side local-tool guard (#S5/#S6). #G5.
 * Redacting secret-looking fields from the dev-mode Inspector feed before any sink (window.__ginaData, localStorage.__ginaData, /_gina/agent SSE, engine.io push, ginaToolbar forms/XHR overlays). New lib/inspector-redact deep-clones the Inspector payload and replaces values whose keys match the default regex (password, pwd, secret, token, apikey, cvv, ssn, authorization, credentials, private_key) with [redacted]. Two complementary carve-outs preserve validation metadata: (1) NON_SECRET_SUFFIX — keys ending in rule/rules/policy/policies/validator/config/configuration/settings/requirements/strength/constraint/options/schema/definition/spec pass through untouched (e.g. passwordRule, passwordPolicy describe form rules, not user input); (2) primitive-only redaction — when a matched secret key holds an object or array, the walker recurses into it instead of replacing it, because such values are always metadata (e.g. rules.account[password] = {isRequired: true, isString: 7} — an HTML form field name under a rules: section). Nested primitive secrets inside preserved objects are still caught on recursion. Client-side shim in statusbar.html mirrors both carve-outs and additionally redacts any DOM input whose type matches configured types (default: password). Configurable via settings.json inspector.redact.{patterns,types,replacement}. Dev-mode only — the actual HTTP response body is never touched. #R7.
 
 ## 0.3.5 - 2026-04-13
@@ -167,7 +225,7 @@ Internal version bump — no user-facing changes. Repository URLs updated from R
 * Added GitHub Actions CI pipeline — runs the full test suite (494+ tests) on Node.js 18, 20, and 22 on every push and PR to `develop` and `master` (#A1)
 * Stable release now auto-tags, merges to master, and publishes the next alpha to npm
 * SQLite ORM connector v2: entity wiring + SQL method generation from .sql files, Option-B Promise/.onComplete() pattern, connector.js (WAL, FK, synchronous open), 56 unit tests
-* Added llms.txt — LLM-optimised framework reference for Cursor, Copilot, Claude.ai
+* Added llms.txt — machine-readable framework reference following the llms.txt standard for IDE coding assistants
 * Added peerDependencies (all optional) for connector client libraries: couchbase, ioredis, mysql2, pg, mongodb, @scylladb/scylla-driver
 * Added GitHub issue templates (bug_report, feature_request) and PR template
 * SQLite state storage for ~/.gina/ config files (CN2 v3): lib/state.js StateStore routes all state-file writes through node:sqlite (DatabaseSync) for atomic writes and concurrent access safety; JSON sidecars kept for backwards-compat read paths
@@ -324,4 +382,4 @@ Internal version bump — no user-facing changes. Repository URLs updated from R
 ### Security
 * Fixed directory traversal vulnerability (CVE-2023-25345) in the swig template engine: a malicious template using `{% extends %}` or a path starting with `./`, `/`, or `\` could read arbitrary files outside the template root.
 * Removed dead framework version v0.1.1-alpha.1 from the repository. Its package.json declared sanitize-html ^2.5.0 (CVE-2021-26539, CVE-2021-26540 — XSS, high severity) and busboy ^0.2.14 (dicer ReDoS). Neither version nor its dependencies were in use.
-* Removed internal development files from the npm package. The published tarball no longer includes .env, CLAUDE.md, .claude/ (internal notes), .changes/ (changie entries), .changie.yaml, services/ (WIP bundles), vendor benchmark and CI files, library example and test files, locale build sources, and stray backup files. Previously .npmignore did not cover these paths.
+* Removed internal development files from the npm package. The published tarball no longer includes .env, local IDE and tooling configuration files, .changes/ (changie entries), .changie.yaml, services/ (WIP bundles), vendor benchmark and CI files, library example and test files, locale build sources, and stray backup files. Previously .npmignore did not cover these paths.

package/CONTRIBUTING.md

@@ -223,4 +223,4 @@ Open a GitHub issue describing the use case **before** writing code. Features th
 | Name | Role | Profile |
 | --- | --- | --- |
 | Martin Luther | Lead maintainer | [rhinostone.com](https://rhinostone.com) |
-| John Doe | Co-author | [fdelaneau.com](https://fdelaneau.com) |
+| Fabrice DELANEAU | Co-author | [fdelaneau.com](https://fdelaneau.com) |

package/CONVENTIONS.md

@@ -542,6 +542,40 @@ var bundles = [
 
 ---
 
+## 18. CLI Command Conventions
+
+### Scope grammar — positional-absence, not flags
+
+Gina CLI commands that apply to either a single bundle or the whole project use positional-absence to signal scope — **never** a flag like `--scope=bundle` or `--shared`:
+
+| Command form | Scope |
+|---|---|
+| `gina <group>:<action> <bundle> @<project>` | Bundle-only |
+| `gina <group>:<action> @<project>` | Project-wide (all bundles + any `shared/config/` overlay) |
+
+Precedents: `bundle:list`, `service:list`, `inspector:open`, `connector:list` / `add` / `rm` / `migrate` (#CN10).
+
+**Why no `--scope`:** the word `scope` is reserved in gina for data isolation (`local` / `beta` / `production` / `testing`) — mixing CLI-scope meaning into the same word is ambiguous.
+
+**Why no `--shared`:** positional-absence is shorter, consistent with the existing grammar, and doesn't invent a new flag surface. If a command needs to address the `shared/config/` file specifically (vs. "all bundles"), document the semantics on that command instead of adding a flag.
+
+**Rule:** when a new CLI command needs a bundle-or-project distinction, follow the `[<bundle>] @<project>` pattern. Do not reintroduce flag-based scope selection.
+
+### Reserved CLI flags — `--port` and `--version`
+
+Two flag names are reserved by the framework's global CLI parser and must **not** be used as subcommand-specific flags:
+
+| Reserved flag | Framework meaning |
+|---|---|
+| `--port` | Runtime bundle port (consumed by `bundle:start` and related runtime commands) |
+| `--version` | Global gina version request (handled before subcommand dispatch) |
+
+**If a subcommand genuinely needs one of these semantics for a different purpose, rename with a qualified prefix.** Precedent set by #CN10 session 2 (`connector:add`): `--connector-port=` for the connector-entry port, `--driver-version=` for the npm driver version range. The un-prefixed forms are swallowed by the framework parser and the subcommand never sees them.
+
+**Rule:** at design time for any new CLI command, grep `lib/cmd/**/arguments.json` and the global parser for reserved names before settling on flag names. If a candidate name collides, prefix it with the subcommand's domain (`--connector-port`, `--driver-version`, etc.) instead of hoping the parser will route it correctly.
+
+---
+
 ## Known Anti-Patterns
 
 | Anti-pattern | Location | Risk | Roadmap item |
@@ -604,3 +638,21 @@ it('name', async function() {
 **Rule**
 
 > Every async `it()` block must either be declared `async` or explicitly `return` a Promise. Any test that calls an async API without doing either will silently pass without testing anything.
+
+---
+
+## Debugging — measurement gotchas
+
+Two reusable lessons that sit under the global "no fix without measurement" rule and refine *how* to measure.
+
+### `setAttribute` writes are not painting
+
+A DOM attribute mutation is only a visible change if a CSS selector or JS observer reads it. Before treating an attribute write as the user-visible bug, confirm a reader exists — grep the deployed CSS for the selector, grep the JS for `getAttribute` / `MutationObserver` / `querySelector` on the attr. If nothing reads it, the write is dead metadata and cannot be the symptom no matter how often it fires. Same applies to class additions that have no rule, dataset writes that no script consumes, and ARIA attributes with no AT in the loop.
+
+### Pre-state matters more than the action
+
+When a bug is described as "X happens when I do Y", lock the visible **pre-state of X** before running Y. The same Y can produce wildly different measurements against different pre-states.
+
+In DOM bugs especially, "errors visible" (post-paint) and "errors appearing" (paint event) look identical in a screenshot but mean opposite things in a diff. If the pre-state already contains the symptom, the action diff is silent and you'll wrongly conclude "not reproducing."
+
+Operational shortcut: ask the reporter for one sentence in user words describing the scenario before guessing the pre-state from code. A single sentence ("other fields not already filled get error messages") can disambiguate hours of wrong-pre-state runs in seconds.

package/GOVERNANCE.md

@@ -2,7 +2,7 @@
 
 Gina follows the **BDFL** (Benevolent Dictator For Life) model with a commitment to transparency.
 
-Gina is co-authored by **Martin Luther** ([Rhinostone](https://rhinostone.com)) and **John Doe** ([fdelaneau.com](https://fdelaneau.com)). Final decisions on direction, API design, and releases rest with Martin Luther. Community contributions and RFCs are welcome and taken seriously.
+Gina is co-authored by **Martin Luther** ([Rhinostone](https://rhinostone.com)) and **Fabrice DELANEAU** ([fdelaneau.com](https://fdelaneau.com)). Final decisions on direction, API design, and releases rest with Martin Luther. Community contributions and RFCs are welcome and taken seriously.
 
 ## How decisions are made
 

package/LICENSE

@@ -1,3 +1,5 @@
+MIT License
+
 Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -37,12 +37,14 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.3.6
+## What's in 0.3.7
 
-- **Inspector payload redaction** — passwords, tokens, API keys, and secret-like fields are automatically stripped from all four Inspector data sinks (`window.__ginaData`, `localStorage`, `/_gina/agent` SSE, `ginaToolbar.update`). Configurable patterns via `inspector.redact` in bundle settings. Metadata carve-outs preserve validation rules and object-valued config under secret keys
-- **CORS preflight fix** — `completeHeaders()` no longer overwrites the echoed `access-control-allow-headers` on preflight responses, fixing browser CORS errors when the bundle's static ACAH list didn't include all client-sent headers
-- **Whisper silent-pass** — `whisper()` no longer emits a red stack trace on missing dictionary keys (first-install UX fix); `post_install.js` now seeds `def_global_mode` so the key is always present
-- See 0.3.5 for the swig 1.5.0 security extension, and 0.3.4 for the `require('gina/gna')` stale-path fix
+- **Model Context Protocol (MCP) support** — `gina bundle:mcp` generates an MCP tool manifest (`mcp.json`) from `routing.json`. `gina bundle:mcp-start` runs a live MCP server over stdio (JSON-RPC 2.0) that dispatches `tools/call` as real HTTP requests against the running bundle. Any Gina app is now consumable by MCP-compatible IDE and agent tooling out of the box. MCP spec revision 2025-06-18
+- **Standalone Inspector SPA + dual-mode resolution** — Inspector can now run as a separate single-page app served from its own origin, with the target bundle passed as `?target=<origin>`. The dev-mode statusbar and `gina inspector:open` both resolve the URL via a 4-level fallback (`--url=` → bundle `config/settings.json > inspector.url` → `~/.gina/<shortVersion>/settings.json > inspector.url` → embedded `<target>/_gina/inspector/`), covering host-SPA + Docker-bundle splits
+- **Inspector Reveal toggle** — dev-mode red-tinted toggle that swaps the redacted `__ginaData` for the unredacted snapshot via `/_gina/reveal`; only bundles running in `local` scope serve it, beta/production/testing return 403. Redactor now tokenizes camelCase so identifiers like `companyName` / `passportRequired` are no longer false-positive-redacted
+- **`service:list` + `bundle:list` port and running-state columns** — both commands now show each bundle's preferred dev port and whether the process is alive, read from `~/.gina/ports.reverse.json` and `~/.gina/run/<bundle>@<project>.pid`
+- **Explicit exports from `require('gina')`** — every framework-injected global (`getContext`, `_`, `requireJSON`, `merge`, …) is now also reachable as a named property on `require('gina')` / `require('gina/gna')`, with JSDoc and auto-generated `types/gna.d.ts`. Runtime globals unchanged
+- See 0.3.6 for Inspector payload redaction + CORS preflight fix, and 0.3.5 for the swig 1.5.0 security extension
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 
@@ -65,7 +67,7 @@ Full installation guide, tutorials, configuration reference, and API docs at **[
 
 ## Governance
 
-Gina is co-authored by **Martin Luther** ([Rhinostone](https://rhinostone.com)) and **John Doe** ([fdelaneau.com](https://fdelaneau.com)). Final decisions on direction, API design, and releases rest with Martin Luther. Community contributions and RFCs are welcome and taken seriously. See [GOVERNANCE.md](./GOVERNANCE.md) for details.
+Gina is co-authored by **Martin Luther** ([Rhinostone](https://rhinostone.com)) and **Fabrice DELANEAU** ([fdelaneau.com](https://fdelaneau.com)). Final decisions on direction, API design, and releases rest with Martin Luther. Community contributions and RFCs are welcome and taken seriously. See [GOVERNANCE.md](./GOVERNANCE.md) for details.
 
 ## License (MIT)
 

package/ROADMAP.md

@@ -100,6 +100,7 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | --- | --- | --- | --- |
 | ✅ | **Explicit exports for global helpers** — `getContext`, `setContext`, `_`, `requireJSON` etc. available as explicit `require('gina/gna').getContext` imports alongside the existing global injection. Enables IDE navigation and static analysis. | `0.3.3-alpha.3` | 2026-04-09 |
 | ✅ | **TypeScript declaration files** — `.d.ts` declarations for the public surface: `SuperController`, `EntitySuper`, connector config shapes, `routing.json` schema, `PathObject`, `uuid`, all config file interfaces, `GinaRequest`/`GinaResponse`. No TS migration of internals — just declarations for consumer projects. `package.json` wired with `"types"` and `"typesVersions"`. | `0.3.3-alpha.3` | 2026-04-09 |
+| ✅ | **Auto-generated `types/gna.d.ts` from JSDoc** (#M9) — `script/generate_gna_types.js` reads the `GLOBAL_EXPORTS` inventory from the gna-exports unit test plus the JSDoc on `framework/v*/core/gna.js` and emits `types/gna.d.ts` with one entry per global export. Two npm scripts: `npm run types:gen` regenerates, `npm run types:check` exits non-zero if drifted. A `gna-types-drift.test.js` unit test re-runs the generator in memory on every test pass — the JSDoc on `core/gna.js` is the single source of truth. Closes the #M8 → #M9 loop and removes the hand-written declaration. | `0.3.7-alpha.2` | 2026-04-18 |
 | 📋 | **`gina connector:audit [@project]`** — reads `connectors.json`, maps each declared connector to its npm peer package (`mysql2`, `pg`, `ioredis`, `couchbase`, `openai`, `@anthropic-ai/sdk`, etc.), and runs `npm audit --json` scoped to those packages in the project's `node_modules`. Reports CVEs with severity and fix availability. If `socket` is installed in the project, delegates to it for supply-chain analysis (malware, typosquatting, protestware) instead of `npm audit`. Exit code 1 on any high/critical finding — CI-friendly. Only audits packages actually declared in `connectors.json`, not the full dependency tree. | `0.4.0` | Q4 2026 |
 
 ### Phase 5 — Future
@@ -107,10 +108,21 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | 📋 | **ESM compatibility layer** — Dual CJS/ESM entry points via `"exports"` in `package.json`. Framework internals stay CJS; public API gets ESM re-exports. | `0.5.0` | Q1 2027 |
-| 📋 | **Pluggable template engine** — Swig 1.4.2 stays fully integrated and remains the default. Nunjucks added as a supported alternative (opt-in per project via config). The render layer is abstracted behind a common interface so both engines co-exist. Switching to Nunjucks requires a per-project migration guide (breaking differences: `{% parent %}` → `{{ super() }}`, filter renames, autoescape default, `date` format strings, no `{% spaceless %}` — see docs). | `0.5.0` | Q1 2027 |
+| 🚧 | **Pluggable template engine** — **Partially shipped in `0.3.7`**: opt-in `render.engine = "nunjucks"` dispatch per bundle. The project installs `nunjucks` itself (no framework dep); Gina loads it via `lib/nunjucks-resolver` and routes through `controller.render-nunjucks.js`. Swig remains the default, runs unchanged. Inspector dev payload, HTTP/2 `stream.respond()` direct path, and error-page template routing all shipped in `0.3.7-alpha.2`. **Closing the parity gap on the `0.3.7` ASAP track** (see Nunjucks Parity below): filter registry port, `setResources` / `<gina>` layout placeholders, static HTML cache parity, Early Hints 103 auto-send. **Remaining `0.5.0` scope**: within-Inspector sub-items (`statusbar.html` include + flow/queries pipelines); per-template-extension dispatch so a single bundle can mix engines (`.swig` / `.njk`); optional auto-detect on `.njk` presence. Breaking syntax differences (`{% parent %}` → `{{ super() }}`, filter renames, `autoescape` default, `date` format strings, no `{% spaceless %}`) are nunjucks's own — Gina doesn't paper over them. | `0.5.0` | Q1 2027 |
 | 📋 | **Structured logging** — JSON log output (`{ level, message, bundle, requestId, durationMs }`). Additive — existing consumers are unaffected. Enables log aggregation (Loki, Datadog, CloudWatch). | `0.5.0` | Q1 2027 |
 | 📋 | **Research `AsyncLocalStorage` for request context** — Evaluate `node:async_hooks` `AsyncLocalStorage` as a replacement for the `local` closure pattern, giving true async isolation across `setTimeout`, Promises, and `async/await` chains without any closure threading. Output: decision doc + proof-of-concept branch. | `0.5.0` | Q1 2027 |
 
+### Nunjucks Parity (`0.3.7` ASAP track)
+
+Four focused follow-up sessions to close the deferred gap left by the `0.3.7-alpha.2` nunjucks MVP. Ordered by user impact.
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 🔨 | **Port `lib/swig-filters` → `lib/nunjucks-filters`** — Mechanically port the 7 filters (`getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears`) into a sister library registered via `env.addFilter()` in `controller.render-nunjucks.js`. Closes the most user-visible gap — template authors get `{{ '/home' \| getUrl() }}` and the date helpers immediately. | `0.3.7` | Q4 2026 |
+| 🔨 | **`setResources` / `<gina>` layout placeholders** — Port the asset-cataloguing pipeline so build-time `<link>` / `<script>` tags are auto-injected into nunjucks layouts the same way they are into swig layouts. `data.page.view.stylesheets` / `.scripts` now populated before render; post-render `injectAssets` helper auto-injects stylesheets before `</head>`, scripts before `</body>` (or before `</head>` when `javascriptsDeferEnabled`), plus `externalPlugins` and the `ginaLoader` before `</head>`. Templates may opt in explicitly with `{{ page.view.stylesheets \| safe }}` — exact-substring detection skips the auto-inject when they do. | `0.3.7` | Q4 2026 |
+| 📋 | **Static HTML cache parity** — Port the swig disk-write/serve cache path so `cache:` keys in `routing.json` actually produce cached HTML for nunjucks routes. | `0.3.7` | Q4 2026 |
+| 📋 | **Early Hints 103 auto-send for CSS/JS preloads** — Move the 103 path in `controller.js this.render()` to be engine-agnostic. Pure perf optimisation; manual `self.setEarlyHints(linkHeader)` already works. | `0.3.7` | Q4 2026 |
+
 ---
 
 ## Connectors
@@ -128,6 +140,7 @@ New database connectors follow the same interface as the existing Couchbase conn
 | ✅ | **Couchbase SDK v2 deprecation** | `0.2.0` | 2026-03-27 | Couchbase Server SDK v2 reached end-of-life in 2021. `connector.v2.js` now logs a deprecation warning at connection time, and a fatal error when V8 pointer compression is active (NAN bindings are incompatible). Upgrade path: set `sdk.version` to `3` or `4` in your bundle's `connectors.json`. |
 | 📋 | **Couchbase SDK v2 removal** | `0.4.0` | Q4 2026 | `connector.v2.js` and all `sdk.version <= 2` branches removed. Default falls back to v3 when `sdk.version` is unset. Full migration guide in `CHANGELOG.md`. |
 | ✅ | **`peerDependencies` for connector clients** | `0.3.0` | 2026-04-01 | All connector client libraries (`ioredis`, `mysql2`, `pg`, `mongodb`, `@scylladb/scylla-driver`, `couchbase`, `openai`, `@anthropic-ai/sdk`) are declared as optional `peerDependencies`. Signals the tested version range to npm/yarn and surfaces a compatibility warning when a user pins an untested version. Zero framework runtime dependency — clients are always loaded from the project's `node_modules`. |
+| ✅ | **`connector:*` CLI group + lint/fix migration** | `0.3.8` | Q2 2026 | New CLI for managing `connectors.json` at project (shared) or bundle scope: `connector:list`, `connector:add`, `connector:rm`, `connector:migrate`. Positional-absence signals scope — omit `<bundle>` to operate on `shared/config/connectors.json`, include it to operate on the bundle's own. `list` cross-references declared connectors against the project's `node_modules` and prints install status per driver. `add` writes the JSON entry and prints the exact `npm install <driver>@<range>` command (no auto-install in v1). `rm` supports `--dry-run` / `--force` and scans sibling bundles for usage before removing at project scope. `migrate` lints every `connectors.json` (or a single bundle's file) and, with `--fix`, injects missing `$schema` entries while preserving comment headers and key order — dry-run by default. Framework-side auto-migrate hook deferred to `0.4.0` alongside the Couchbase SDK v2 removal where a concrete old-shape → new-shape delta will justify touching the boot path. Adds a `version` property to the `connectors.json` schema for install-version resolution. Optional follow-up: `--install` flag with lockfile-based package manager detection. **Session 1 (`connector:list`) shipped 2026-04-21, `0.3.7-alpha.3`** — read-only lister with overlay/override detection, driver install probing, version-pin disagreement warnings, JSON output, 89 source-inspection unit tests. **Session 2 (`connector:add` + schema `version`) shipped 2026-04-21, `0.3.7-alpha.3`** — writes shared or bundle-scoped connector entries, infers type from `<name>`, preserves comment headers and key order, pins `$schema` at the top, rejects overwrites without `--force`, prints `npm install <pkg>@"<range>"` install hint (AI resolves per protocol scheme, sqlite short-circuits to built-in note), adds `version` property to `schema/connectors.json`. 94 source-inspection unit tests; 7 live smoke tests. CLI flag rename (`--connector-port=`/`--driver-version=`) avoids framework-reserved `--port`/`--version`. **Session 3 (`connector:rm`) shipped 2026-04-21, `0.3.7-alpha.3`** — removes shared or bundle-scoped entries via positional-absence scoping (`remove` alias accepted); `--dry-run` previews without writing; `--force` skips the project-level usage guard that otherwise refuses when any bundle still references the same logical name; driver-retention hint prints after every removal naming sibling bundles that still use the same driver (sqlite exempt — built-in); inherited-from-shared hint fires when rm from a bundle targets an entry declared only in shared. Never runs `npm uninstall`. 81 source-inspection unit tests. **Session 4 (`connector:migrate`) shipped 2026-04-21, `0.3.7-alpha.3`** — CLI-only linter: dry-run by default, `--fix` applies auto-fixable issues in place. Two detection types: `missing-schema` (auto-fixable, injects `"$schema": "https://gina.io/schema/connectors.json"` pinned at top while preserving comment header and key order) and `bare-key-no-connector` (entry key not in `couchbase, mysql, postgresql, sqlite, redis, ai` enum with no `connector` field — warn-only since driver cannot be inferred). Two invocation modes via positional-absence: `@<project>` scans shared + every bundle; `<bundle> @<project>` scans just that bundle. `--format=json` emits `{project, scope, bundle, fixApplied, files[]}` envelope for CI. Registered as offline — no framework socket required. Idempotent. Never modifies `core/config.js` and never runs at bundle boot — explicit and opt-in. Real framework-side hook deferred to `0.4.0` alongside Couchbase SDK v2 removal. 87 source-inspection unit tests; full write-path smoke test on a disposable sandbox (shared + two bundles), plus a no-false-positive smoke on a real 7-bundle project. |
 
 ---
 
@@ -224,7 +237,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **OpenAPI spec generation** — `gina bundle:openapi @myproject` emits `openapi.json` from `routing.json`. Zero manual spec writing — route annotations become `description` fields. Makes any Gina app consumable by AI agents, API gateways, and testing tools. Alias: `bundle:oas`. Supports `--output` flag for custom path. | `0.3.3-alpha.2` | 2026-04-08 |
-| 📋 | **MCP server wrapper** — `gina bundle:mcp @myproject` exposes `routing.json` routes as MCP (Model Context Protocol) tools. Makes any Gina app a native MCP server discoverable by AI agents. | `0.4.0` | Q4 2026 |
+| ✅ | **MCP server wrapper** — Phase 1 (done, `0.3.7-alpha.2`, 2026-04-18): `gina bundle:mcp @myproject` emits a static MCP tool manifest (`mcp.json`) targeting MCP spec revision 2025-06-18. Phase 2a (done, `0.3.7-alpha.3`, 2026-04-18): `gina bundle:mcp-start <bundle> @myproject` serves the manifest as a live MCP server over stdio (JSON-RPC 2.0, newline-delimited). `tools/call` is dispatched as real HTTP requests against the running bundle. Phase 2b (done, `0.3.7-alpha.2`, 2026-04-22): Streamable HTTP transport for remote/containerised agents — `gina bundle:mcp-start <bundle> @myproject --transport=http`. Opt-in static bearer auth via `--auth-token`, built-in loopback `Origin` allowlist, full CORS echo, SSE response mode, JSON-RPC 2.0 batch, `Mcp-Session-Id` lifecycle. OAuth 2.1 intentionally out of scope — deploy behind a reverse proxy. Live end-to-end smoke recipe ready for the next alpha release. | `0.3.7-alpha.2` | 2026-04-22 |
 
 ---
 

package/bin/cli

@@ -1,6 +1,17 @@
 #!/usr/bin/env node
 'use strict';
 
+// MCP stdio transport isolation (#AI8b).
+// `gina bundle:mcp-start` speaks JSON-RPC on stdout. Anything else written
+// to process.stdout (framework logger, bootstrap noise, console.log) would
+// corrupt the wire and kill the MCP client parser on the first byte.
+// Stash the real write and redirect the rest to stderr before any framework
+// module loads. The handler reads the real write from process.__ginaMcpStdout.
+if (process.argv.indexOf('bundle:mcp-start') > -1) {
+    process.__ginaMcpStdout = process.stdout.write.bind(process.stdout);
+    process.stdout.write = process.stderr.write.bind(process.stderr);
+}
+
 var fs              = require('fs');
 var net             = require('net');
 var util            = require('util');
@@ -302,6 +313,7 @@ async function onExec() {
         'build:',
         'bundle:',
         'cache:',
+        'connector:',
         'dev:',
         'env:',
         'inspector:',
@@ -312,6 +324,7 @@ async function onExec() {
         'project:',
         'protocol:',
         'scheme:',
+        'service:',
         'view:',
         '--', //options or other aliases.
         '-' //options or other aliases.

package/framework/{v0.3.7-alpha.1 → v0.3.7-alpha.3}/AUTHORS

@@ -3,5 +3,5 @@
 #
 
 Martin Luther ETOUMAN <contact@gina.io>
-John Doe <contact+gina@fdelaneau.com>
+Fabrice DELANEAU <contact+gina@fdelaneau.com>
 Stephane HEAV <stephane.heav@gmail.com>

package/framework/{v0.3.7-alpha.1/lib/inherits → v0.3.7-alpha.3}/LICENSE

@@ -1,3 +1,5 @@
+MIT License
+
 Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/framework/v0.3.7-alpha.3/VERSION

@@ -0,0 +1 @@
+0.3.7-alpha.3