cabloy 5.1.192 → 5.1.194

package/repo-agent-governance/tools/contract-loop/hook-runtime.mjs

@@ -0,0 +1,368 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  analyze,
+  analyzePath,
+  buildMessages,
+  isCodeFile,
+  isHighConfidenceReverseSource,
+  normalizePath,
+  resolveEdition,
+  toPosixPath,
+} from './core.mjs';
+
+const STATE_FILE = path.join(os.tmpdir(), 'cabloy-contract-loop-gate-state.json');
+const AUTO_SYNC_WINDOW_SECONDS = 300;
+
+function readText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function isDirectory(filePath) {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function canonicalPath(filePath) {
+  let current = filePath;
+  const missingSegments = [];
+  for (;;) {
+    try {
+      return path.resolve(realpathSync(current), ...missingSegments);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return filePath;
+      missingSegments.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(canonicalPath(root), canonicalPath(candidate));
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..');
+}
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state) {
+  try {
+    writeFileSync(STATE_FILE, JSON.stringify(state), 'utf8');
+  } catch {
+    // State prevents duplicate convenience syncs only; it must not block guidance.
+  }
+}
+
+function syncFingerprint(filePath) {
+  try {
+    const stats = statSync(filePath, { bigint: true });
+    return `${filePath}:${stats.mtimeNs.toString()}`;
+  } catch {
+    return filePath;
+  }
+}
+
+function shouldSkipAutoSync(root, filePath) {
+  const state = loadState();
+  const entry = state[toPosixPath(root)];
+  return Boolean(
+    entry &&
+    entry.fingerprint === syncFingerprint(filePath) &&
+    Date.now() - entry.timestamp <= AUTO_SYNC_WINDOW_SECONDS * 1000,
+  );
+}
+
+function markAutoSync(root, filePath) {
+  const state = loadState();
+  state[toPosixPath(root)] = { fingerprint: syncFingerprint(filePath), timestamp: Date.now() };
+  saveState(state);
+}
+
+function runNpm(root, args) {
+  const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(command, [...args], { cwd: root, encoding: 'utf8' });
+}
+
+function summarizeProcess(result) {
+  if (result.error) return result.error.message;
+  const combined = [result.stdout?.trim(), result.stderr?.trim()].filter(Boolean).join('\n');
+  const exitCode = result.status ?? 1;
+  if (!combined) return `command exited with code ${exitCode}`;
+  return `exit ${exitCode}: ${combined
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(-3)
+    .join(' | ')}`;
+}
+
+function autoSyncReverse(root, filePath, edition) {
+  for (const command of edition.reverseAutoSyncCommands) {
+    const result = runNpm(root, command.args);
+    if (result.status !== 0) {
+      return {
+        kind: 'failure',
+        message: `Auto-sync failed during \`${command.display}\`: ${summarizeProcess(result)}`,
+      };
+    }
+  }
+  markAutoSync(root, filePath);
+  return {
+    kind: 'success',
+    message: `Auto-sync ran ${edition.reverseAutoSyncCommands
+      .map(command => `\`${command.display}\``)
+      .join(' and ')} for this ${edition.label} reverse-chain edit.`,
+  };
+}
+
+export function resolveReverseSyncOutcome(root, filePath, reverseReason) {
+  if (!reverseReason) return { kind: 'not-applicable', message: '' };
+  if (!isHighConfidenceReverseSource(filePath)) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+    };
+  }
+  const resolution = resolveEdition(root);
+  if (resolution.kind !== 'resolved') {
+    return {
+      kind: 'not-applicable',
+      message: `Auto-sync did not run because ${resolution.kind === 'ambiguous' ? 'both Cabloy edition markers are present' : 'no Cabloy edition marker is present'}.`,
+    };
+  }
+  if (shouldSkipAutoSync(root, filePath)) {
+    return {
+      kind: 'skipped',
+      message:
+        'Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.',
+    };
+  }
+  return autoSyncReverse(root, filePath, resolution.edition);
+}
+
+export function readHookPayload() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function extractClaudeEditedFilePath(payload) {
+  const filePath = payload?.tool_input?.file_path;
+  return typeof filePath === 'string' && filePath ? filePath : null;
+}
+
+export function extractCodexEditedFiles(payload) {
+  const command = payload?.tool_input?.command;
+  if (typeof command !== 'string') return [];
+  const entries = [];
+  let pendingUpdate = null;
+  const headerPattern = /^\*\*\* (Add|Update|Delete) File:(.+)$|^\*\*\* Move to:(.+)$/;
+
+  const flushUpdate = () => {
+    if (pendingUpdate) entries.push(pendingUpdate);
+    pendingUpdate = null;
+  };
+
+  for (const line of command.split(/\r?\n/)) {
+    const match = headerPattern.exec(line);
+    if (!match) continue;
+    const [, verb, sourcePath, destinationPath] = match;
+    if (destinationPath !== undefined) {
+      if (pendingUpdate) pendingUpdate.filePath = destinationPath.trim();
+      continue;
+    }
+    flushUpdate();
+    const filePath = sourcePath.trim();
+    if (!filePath) continue;
+    const operation = verb.toLowerCase();
+    if (operation === 'update') {
+      pendingUpdate = { operation, filePath };
+    } else {
+      entries.push({ operation, filePath });
+    }
+  }
+  flushUpdate();
+  return entries;
+}
+
+// Retain the path-only export for callers that only need the historical view.
+export function extractCodexEditedFilePaths(payload) {
+  return extractCodexEditedFiles(payload).map(entry => entry.filePath);
+}
+
+export function extractCursorEditedFilePath(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  if (typeof payload.file_path === 'string' && payload.file_path) return payload.file_path;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object') return null;
+  for (const key of ['path', 'file_path', 'target_file']) {
+    const value = input[key];
+    if (typeof value === 'string' && value) return value;
+  }
+  return null;
+}
+
+export function inferCursorHookEvent(payload) {
+  const eventName = payload?.hook_event_name;
+  if (
+    eventName === 'afterFileEdit' ||
+    eventName === 'afterTabFileEdit' ||
+    eventName === 'postToolUse'
+  ) {
+    return eventName;
+  }
+  if (typeof payload?.file_path === 'string' && payload.file_path && !payload.tool_name) {
+    return 'afterFileEdit';
+  }
+  return 'postToolUse';
+}
+
+export function formatClaudeHookOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+    systemMessage: message,
+  };
+}
+
+export function formatCodexHookOutput(message) {
+  return {
+    hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: message },
+    systemMessage: message,
+  };
+}
+
+export function formatCursorHookOutput(message, eventName) {
+  if (eventName !== 'postToolUse') return null;
+  return { additional_context: message };
+}
+
+function resolvePathBase(root, candidate) {
+  if (typeof candidate !== 'string' || !candidate) return root;
+  const pathBase = normalizePath(root, candidate);
+  if (!pathBase || !isInside(root, pathBase) || !isDirectory(pathBase)) return root;
+  return pathBase;
+}
+
+function createInspectionFailure(root, filePath, operation) {
+  const relativePath = toPosixPath(path.relative(root, filePath));
+  return {
+    kind: 'failure',
+    filePath,
+    message: `Contract-loop gate: could not inspect edited source \`${relativePath}\` after this ${operation} patch; no contract-loop guidance or auto-sync ran.`,
+  };
+}
+
+function inspectEditedFile(root, rawPath, { operation = 'update', pathBase = root } = {}) {
+  const filePath = normalizePath(pathBase, rawPath);
+  if (!filePath || !isInside(root, filePath) || !isCodeFile(filePath)) return null;
+
+  const resolution = resolveEdition(root);
+  if (operation === 'delete') {
+    const result = analyzePath(filePath);
+    if (!result.forwardReason && !result.reverseReason) return null;
+    return { kind: 'signal', filePath, resolution, result };
+  }
+
+  const content = readText(filePath);
+  if (content === null) return createInspectionFailure(root, filePath, operation);
+  const result = analyze(
+    filePath,
+    content,
+    resolution.kind === 'resolved' ? resolution.edition : null,
+  );
+  if (!result.forwardReason && !result.reverseReason) return null;
+  return { kind: 'signal', filePath, resolution, result };
+}
+
+export function evaluateEditedFile(root, rawPath) {
+  const inspected = inspectEditedFile(root, rawPath);
+  if (!inspected || inspected.kind !== 'signal') return null;
+  const { filePath, resolution, result } = inspected;
+  const reverseSyncOutcome = resolveReverseSyncOutcome(root, filePath, result.reverseReason);
+  return {
+    filePath,
+    message: buildMessages(result, resolution, reverseSyncOutcome),
+  };
+}
+
+export function evaluateCodexEditedFiles(root, entries, payloadCwd) {
+  const pathBase = resolvePathBase(root, payloadCwd);
+  const seenEntries = new Set();
+  const inspected = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry.filePath !== 'string') continue;
+    const operation = ['add', 'update', 'delete'].includes(entry.operation)
+      ? entry.operation
+      : 'update';
+    const normalizedPath = normalizePath(pathBase, entry.filePath);
+    if (!normalizedPath || !isInside(root, normalizedPath)) continue;
+    const key = `${operation}:${normalizedPath}`;
+    if (seenEntries.has(key)) continue;
+    seenEntries.add(key);
+    const item = inspectEditedFile(root, entry.filePath, { operation, pathBase });
+    if (item) inspected.push(item);
+  }
+
+  const autoSyncItem = inspected.find(
+    item =>
+      item.kind === 'signal' &&
+      item.result.reverseReason &&
+      isHighConfidenceReverseSource(item.filePath),
+  );
+  const autoSyncOutcome = autoSyncItem
+    ? resolveReverseSyncOutcome(root, autoSyncItem.filePath, autoSyncItem.result.reverseReason)
+    : null;
+
+  return inspected.map(item => {
+    if (item.kind === 'failure') return { filePath: item.filePath, message: item.message };
+
+    let reverseSyncOutcome;
+    if (item === autoSyncItem) {
+      reverseSyncOutcome = autoSyncOutcome;
+    } else if (item.result.reverseReason && isHighConfidenceReverseSource(item.filePath)) {
+      reverseSyncOutcome = {
+        kind: 'skipped',
+        message:
+          'Auto-sync skipped because another high-confidence reverse-source file in this Codex edit was already handled.',
+      };
+    } else {
+      reverseSyncOutcome = resolveReverseSyncOutcome(
+        root,
+        item.filePath,
+        item.result.reverseReason,
+      );
+    }
+    return {
+      filePath: item.filePath,
+      message: buildMessages(item.result, item.resolution, reverseSyncOutcome),
+    };
+  });
+}
+
+// Keep the prior general API for direct callers. Codex now uses the operation-aware evaluator.
+export function evaluateEditedFiles(root, rawPaths) {
+  return evaluateCodexEditedFiles(
+    root,
+    rawPaths.map(filePath => ({ operation: 'update', filePath })),
+  );
+}

package/repo-docs/ai/agent-governance.md

@@ -15,14 +15,16 @@ npm run agent:governance:check
 
 The committed repository adapter outputs are:
 
-| Agent surface | Generated repository assets                                                                    |
-| ------------- | ---------------------------------------------------------------------------------------------- |
-| Claude Code   | `CLAUDE.md`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, `.claude/hooks/` |
-| Codex         | `AGENTS.md`, `.agents/skills/`                                                                 |
-| Cursor        | `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`                                       |
+| Agent surface | Generated repository assets                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| Claude Code   | `CLAUDE.md`, `.claude/skills/`, `.claude/commands/`, `.claude/settings.json`, `.claude/hooks/`   |
+| Codex         | `AGENTS.md`, `.agents/skills/`, `.codex/hooks.json`, `.codex/hooks/`                             |
+| Cursor        | `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/hooks/` |
 
 The same root rule and skill sources are copied to every listed adapter. Platform-specific discovery metadata is intentionally thin and lives in the adapter layer. The generated Codex and Cursor skill paths are configured adapter locations; their client discovery behavior requires a version-pinned external smoke check before it is claimed as supported.
 
+Codex requires the user to trust project-local hooks before it runs `.codex/hooks.json`; that local trust state is not generated or committed by this repository. The repository launcher resolves a hook from nested working directories without Git once Codex invokes it, but Codex discovery remains client-version behavior. For non-Git projects opened from nested directories, configure local Codex `project_root_markers` to include `__CABLOY_BASIC__` and `__CABLOY_START__` alongside `.git`; do not generate that user setting from this repository.
+
 ### Package migration bridge
 
 The transition package deliberately excludes generated root adapters because the immediately preceding upgrader overwrites those paths before it starts the incoming initializer. This prevents that legacy path from silently replacing customized adapters. The package still includes canonical governance and `scripts/init.ts`; `npm run init` performs ownership-aware adoption for both a staged upgrade and a fresh project. A source checkout retains its committed generated adapters. This bridge is package-transition behavior, not a claim that agents generate instructions at startup.
@@ -31,7 +33,7 @@ The transition package deliberately excludes generated root adapters because the
 
 Rules, procedural skills, references, eval fixtures, contract-loop analysis, and ordinary deterministic repository tools are portable.
 
-Hooks, tool permissions, local settings, credentials, MCP registration, slash-command discovery, confirmation UI, and automatic command execution are not portable contracts. Claude Code retains the repository `PostToolUse` contract-loop convenience hook. Codex and Cursor receive the same advisory contract-loop guidance but must not be described as running the Claude hook or its automatic commands.
+Hooks, tool permissions, local settings, credentials, MCP registration, slash-command discovery, confirmation UI, and automatic command execution are not portable contracts. Claude Code, Codex, and Cursor each have a platform-specific contract-loop convenience hook over the same portable classifier and reverse auto-sync runtime. Their hook payloads and stdout contracts differ, so each adapter must remain provider-specific even when it shares the same runtime.
 
 No adapter output owns `settings.local.json`, `CLAUDE.local.md`, worktree state, scheduled-task state, credentials, or arbitrary user-owned agent files.
 

package/repo-docs/ai/docs-skills-rules-mapping.md

@@ -81,6 +81,9 @@ Generated adapter locations include:
 
 - policy adapters: `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/`
 - Claude-specific command adapter: `.claude/commands/`
+- Claude-specific hook adapter: `.claude/settings.json`, `.claude/hooks/`
+- Codex-specific hook adapter: `.codex/hooks.json`, `.codex/hooks/`
+- Cursor-specific hook adapter: `.cursor/hooks.json`, `.cursor/hooks/`
 
 Codex and Cursor adapter paths are configured output locations; verify active-client discovery externally before claiming that behavior is supported.
 
@@ -98,7 +101,7 @@ Canonical location:
 
 - `repo-agent-governance/skills/`
 
-Generated adapter locations include `.claude/skills/`, `.agents/skills/`, and `.cursor/skills/`. The Codex and Cursor locations are configured output paths, not verified client-discovery claims; validate the active client version externally before relying on discovery.
+Generated adapter locations include `.claude/skills/`, `.agents/skills/`, `.codex/`, and `.cursor/skills/`. The Codex and Cursor locations are configured output paths, not verified client-discovery claims; validate the active client version externally before relying on discovery.
 
 Use skills for:
 

package/repo-docs/ai/edition-consistency-checklist.md

@@ -7,7 +7,7 @@ Use it whenever you add or revise:
 - edition-aware docs
 - `repo-agent-governance/` rules, commands, and skill bundles
 - generated Claude, Codex, or Cursor adapter outputs
-- platform-specific Claude commands, hooks, or settings when they are affected
+- platform-specific Claude, Codex, or Cursor commands, hooks, or settings when they are affected
 - AI workflow playbooks
 
 ## The baseline story that should stay consistent

package/repo-docs/ai/introduction.md

@@ -52,7 +52,7 @@ Use `repo-agent-governance/` as the authored source for portable repository rule
 
 ### Platform runtime integration
 
-`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `AGENTS.md`, `.agents/skills/`, and `.cursor/` are adapter/runtime surfaces. Hooks, permissions, local settings, credentials, and provider-specific command discovery stay platform-specific rather than becoming shared framework facts.
+`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `AGENTS.md`, `.agents/skills/`, `.codex/`, and `.cursor/` are adapter/runtime surfaces. Hooks, permissions, local settings, credentials, and provider-specific command discovery stay platform-specific rather than becoming shared framework facts.
 
 ## AI reading paths
 

package/repo-docs/ai/repo-guidance.md

@@ -11,7 +11,7 @@ Check the root repository signals first:
 - `repo-docs-internal/`
 - `repo-specs/` when the task concerns a suite plan, WBS increment, acceptance record, or evidence
 - `repo-agent-governance/` canonical rules, skill bundles, and deterministic tools
-- generated platform adapter assets such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, and `.cursor/`
+- generated platform adapter assets such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, and `.cursor/`
 
 These surfaces tell the agent which repo it is in, which scripts are canonical, and where shared agent instructions are authored. Treat platform directories as generated adapters; regenerate them from `repo-agent-governance/` rather than hand-editing them. Inspect relevant `repo-docs-internal/` records as supporting context rather than as a gate to workflow guidance.
 

package/repo-docs/ai/rules-and-config.md

@@ -21,10 +21,12 @@ npm run test:agent-governance
 The following are committed generated outputs, not parallel authored knowledge sources:
 
 - Claude Code: `CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `.claude/settings.json`, `.claude/hooks/`
-- Codex: `AGENTS.md`, `.agents/skills/`
-- Cursor: `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`
+- Codex: `AGENTS.md`, `.agents/skills/`, `.codex/hooks.json`, `.codex/hooks/`
+- Cursor: `.cursor/rules/cabloy-governance.mdc`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/hooks/`
 
-The Codex and Cursor skill paths are configured generated adapter locations; verify client discovery with a version-pinned external smoke check before presenting it as supported behavior. The adapter model shares rules and procedures, not platform runtime behavior. Claude Code's contract-loop hook is a Claude-specific convenience integration; Codex and Cursor receive advisory guidance but do not claim the same automatic after-edit action.
+The Codex and Cursor skill paths are configured generated adapter locations; verify client discovery with a version-pinned external smoke check before presenting it as supported behavior. The adapter model shares rules and procedures, not hook payload formats. Claude Code, Codex, and Cursor each register a platform-specific contract-loop convenience hook over the same portable runtime.
+
+Codex runs project-local `.codex/hooks.json` only after the user trusts that hook definition. Hook trust is local state and remains outside generated governance ownership. The generated launcher is Git-free once Codex invokes it, but non-Git project discovery from a nested directory remains client-controlled; configure local Codex `project_root_markers` with Cabloy edition markers when that scenario must be supported.
 
 ## Local configuration and permissions
 

package/repo-docs/backend/menu-authorization.md

@@ -18,6 +18,7 @@ An SSR menu item can declare `roles` metadata:
     link: 'presetResource',
     roles: ['systemAdmin'],
   },
+  site: 'basic-siteadmin:admin',
 })
 ```
 

package/repo-docs/backend/menu-guide.md

@@ -57,9 +57,16 @@ In the current repo implementation, the out-of-the-box menu controller is public
 
 ## SSR Site targeting
 
-`@SsrMenu(...)` and `@SsrMenuGroup(...)` use `site` to select the SSR Site onion(s) that receive the declaration. It is a navigation-composition filter, not a site-admission, role-visibility, or backend-authorization decision.
+`@SsrMenu(...)` and `@SsrMenuGroup(...)` require an explicit `site` to select the SSR Site onion(s) that receive the declaration. It is a navigation-composition filter, not a site-admission, role-visibility, or backend-authorization decision.
 
-Use `site` for navigation owned by one SSR Site or deliberately exclusive to a known subset of sites:
+- Use a site string or an array of site strings to target known SSR Sites.
+- Omission, `undefined`, `null`, and empty or whitespace-only strings are invalid, including blank entries in an array.
+- `site: []` is valid and explicitly means no sites receive the declaration.
+- Sharing requires an explicit array of intended sites; there is no wildcard or implicit all-sites scope.
+- Menu and group declarations are independently scoped. A menu does not inherit its group's `site`; declare the intended sites on both.
+- `locale` remains optional: omitting it leaves the declaration unrestricted by locale.
+
+Use a single site string for navigation owned by one SSR Site:
 
 ```typescript
 @SsrMenu({
@@ -69,11 +76,11 @@ Use `site` for navigation owned by one SSR Site or deliberately exclusive to a k
     roles: ['systemAdmin'],
   },
   // This Basic Admin-owned entry intentionally targets one SSR Site.
-  site: ['basic-siteadmin:admin'],
+  site: 'basic-siteadmin:admin',
 })
 ```
 
-For a shared module declaration intended for every compatible SSR Admin site, omit `site`:
+For a shared module declaration, list every intended compatible SSR Admin site explicitly:
 
 ```typescript
 @SsrMenu({
@@ -82,11 +89,15 @@ For a shared module declaration intended for every compatible SSR Admin site, om
     link: 'presetResource',
     roles: ['systemAdmin'],
   },
-  // No `site`: the shared declaration is available to compatible SSR Admin sites.
+  // Share only with these explicitly selected SSR Sites.
+  site: ['basic-siteadmin:admin', 'commerce-siteadmin:commerceAdmin'],
 })
 ```
 
-Do not bind a shared Admin menu or menu group to the current/default Admin site merely to keep a new independent site's navigation narrow. Isolate an independent site through its enabled module composition and site-owned menus/groups. When a shared capability needs genuinely different navigation contracts per site, use an explicit, approved site-specific composition or owner instead of narrowing the shared declaration by default.
+Choose the site list from the intended navigation contract, not merely the current/default Admin site. Isolate an independent site through its enabled module composition and site-owned menus/groups. When a shared capability needs genuinely different navigation contracts per site, use an explicit, approved site-specific composition or owner.
+
+> [!WARNING]
+> This is a breaking change for declarations that previously omitted `site` to reach all sites. Migrate each menu and group to an explicit site string or array, or use `site: []` when it should reach no sites. Add future shared sites to the array deliberately; omission is no longer a sharing mechanism.
 
 `site` is distinct from a role's `siteIds`, menu `roles` or role-menu associations, and Passport/RBAC authorization:
 
@@ -140,6 +151,6 @@ When editing SSR menu behavior, ask:
 2. is there a default fallback menu that should remain available?
 3. does the menu contract belong in backend API design, frontend route design, or both?
 4. does the active edition affect the menu structure or public path assumptions?
-5. is this declaration site-owned or deliberately site-exclusive (specify `site`), or shared across compatible SSR Admin sites (omit `site`)?
+5. does every menu and group declare its own explicit `site` string or array, with all intended shared sites listed and `[]` used only when no sites should receive it?
 
 That helps AI keep menu behavior aligned with Cabloy’s shared SSR architecture.

package/repo-docs/blogs/cabloy-fullstack-resource-addressing/index.md

@@ -219,6 +219,7 @@ The Student SSR menu supplies that context:
       },
     },
   },
+  site: ['basic-siteadmin:admin'],
 })
 export class SsrMenuStudent extends BeanBase {}
 ```

package/repo-docs/reference/package-map.md

@@ -8,7 +8,7 @@ This monorepo is organized around a small set of stable top-level areas.
 - `lerna.json` — package topology
 - `repo-docs-internal/` — edition-local maintainer notes and ADRs
 - `repo-agent-governance/` — authored portable agent rules, root skill bundles, adapter definitions, and deterministic tools
-- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.cursor/` — generated platform adapters plus platform-specific runtime integration
+- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.cursor/` — generated platform adapters plus platform-specific runtime integration
 - `repo-docs/` — unified public docs
 - `repo-specs/` — suite-local product, technical, delivery, ATP, progress, observed-evidence, and ADR authority
 

package/repo-e2e/config/playwright.config.ts

@@ -21,7 +21,7 @@ export default defineConfig({
     : {
         command: 'node repo-e2e/scripts/startE2eVona.ts',
         cwd: E2E_ROOT_DIR,
-        url: `${baseURL}/`,
+        url: `${baseURL}/health/ready`,
         timeout: 180_000,
         reuseExistingServer: false,
         stdout: 'pipe',

package/repo-e2e/scripts/startE2eVona.ts

@@ -2,13 +2,17 @@ import type { ChildProcess } from 'node:child_process';
 
 import { spawn } from 'node:child_process';
 
-import { E2E_ROOT_DIR } from './e2e.ts';
+import { E2E_LOCAL_BASE_URL, E2E_ROOT_DIR } from './e2e.ts';
 
 const child: ChildProcess = spawn('npm', ['run', 'dev:one'], {
   cwd: E2E_ROOT_DIR,
   detached: process.platform !== 'win32',
   stdio: 'inherit',
-  env: process.env,
+  env: {
+    ...process.env,
+    SERVER_SERVE_PROTOCOL: 'http',
+    SERVER_SERVE_HOST: E2E_LOCAL_BASE_URL.replace(/^https?:\/\//, ''),
+  },
 });
 
 const gracefulShutdownTimeout = 7000;