@geraldmaron/construct 1.0.5 → 1.0.7

package/lib/mcp/tools/profile.mjs

@@ -0,0 +1,270 @@
+/**
+ * lib/mcp/tools/profile.mjs — MCP wrappers for the org-profile + learning surfaces.
+ *
+ * Bridges PR #67 capabilities (profiles, outcomes, sandboxes, knowledge_add,
+ * learning status) so subagents talking through the construct-mcp server can
+ * read the same state the CLI exposes. Operator-only surfaces (optimize_apply,
+ * optimize_rollback) remain CLI-only and are not registered here.
+ *
+ * Pattern: each export is a thin schema-validated wrapper around the existing
+ * lib/* function the CLI already uses. Errors return `{ error: string }` so
+ * the MCP dispatcher hands a structured failure back instead of crashing.
+ * Destructive operations (profile_archive) require `confirm: true`, matching
+ * the storage_reset / delete_ingested_artifacts pattern in tools/storage.mjs.
+ */
+import { resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  loadProfile,
+  listProfiles,
+  loadCustomProfile,
+  resolveActiveProfile,
+} from '../../profiles/loader.mjs';
+import {
+  createDraftProfile,
+  listDrafts,
+  archiveProfile,
+  profileHealth,
+} from '../../profiles/lifecycle.mjs';
+import { recordOutcome } from '../../outcomes/record.mjs';
+import { aggregateOutcomes, readSummary } from '../../outcomes/aggregate.mjs';
+import { addResearchFinding } from '../../knowledge/research-store.mjs';
+import { askGlobal } from '../../knowledge/graph.mjs';
+import { listSandboxes } from '../../sandbox.mjs';
+
+function cwdOf(args) {
+  return args && args.cwd ? resolve(String(args.cwd)) : process.cwd();
+}
+
+// Read-only: active profile.
+
+export function profileShow(args = {}) {
+  const cwd = cwdOf(args);
+  const profile = resolveActiveProfile(cwd, args.id ? String(args.id) : null);
+  return {
+    id: profile.id,
+    displayName: profile.displayName ?? profile.id,
+    tagline: profile.tagline ?? null,
+    custom: profile.custom === true,
+    roles: Array.isArray(profile.roles) ? profile.roles : [],
+    departments: Array.isArray(profile.departments)
+      ? profile.departments.map((d) => ({ id: d.id, displayName: d.displayName, roleCount: Array.isArray(d.roles) ? d.roles.length : 0 }))
+      : [],
+    intake: {
+      types: profile.intake?.types ?? [],
+      stages: profile.intake?.stages ?? [],
+    },
+    docTemplates: profile.docTemplates ?? [],
+    hooks: profile.hooks ?? null,
+    rebrand: profile.rebrand ?? null,
+  };
+}
+
+// Read-only: catalog summary.
+
+export function profileList() {
+  return {
+    profiles: listProfiles().map((id) => {
+      const p = loadProfile(id);
+      return p
+        ? {
+            id: p.id,
+            displayName: p.displayName ?? p.id,
+            tagline: p.tagline ?? null,
+            roleCount: Array.isArray(p.roles) ? p.roles.length : 0,
+            departmentCount: Array.isArray(p.departments) ? p.departments.length : 0,
+          }
+        : { id, error: 'failed to parse' };
+    }),
+  };
+}
+
+// Read-only: drafts + custom profile under .cx/.
+
+export function profileDrafts(args = {}) {
+  const cwd = cwdOf(args);
+  const drafts = listDrafts(cwd).map((d) => ({
+    id: d.id,
+    dir: d.dir,
+    hasProfile: d.hasProfile,
+    hasBrief: d.hasBrief,
+  }));
+  const custom = loadCustomProfile(cwd);
+  return {
+    drafts,
+    custom: custom ? { id: custom.id, displayName: custom.displayName ?? custom.id } : null,
+  };
+}
+
+// Read-only: per-profile health rollup.
+
+export function profileHealthTool(args = {}) {
+  const cwd = cwdOf(args);
+  const id = args.id ? String(args.id) : resolveActiveProfile(cwd).id;
+  const windowDays = Number.isFinite(args.window_days) ? Number(args.window_days) : 30;
+  return { id, windowDays, ...profileHealth(cwd, id, { windowDays }) };
+}
+
+// Read-only: outcomes rollup. Optional aggregate=true rebuilds _summary.json.
+
+export function outcomesSummary(args = {}) {
+  const cwd = cwdOf(args);
+  if (args.aggregate === true) {
+    try { aggregateOutcomes(cwd); } catch (err) { return { error: `aggregate failed: ${err.message}` }; }
+  }
+  const summary = readSummary(cwd);
+  if (!summary) return { roles: {}, note: 'no outcomes recorded yet' };
+  return summary;
+}
+
+// Mutating, gated: append an outcome line.
+
+export function outcomesRecord(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'outcomes_record requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.role || typeof args.success !== 'boolean') {
+    return { error: 'outcomes_record requires role:string and success:boolean' };
+  }
+  const profile = args.profile ? String(args.profile) : resolveActiveProfile(cwd)?.id;
+  const file = recordOutcome(cwd, {
+    role: String(args.role),
+    intakeId: args.intake_id ? String(args.intake_id) : null,
+    profile,
+    success: !!args.success,
+    escalated: !!args.escalated,
+    durationMs: Number.isFinite(args.duration_ms) ? Number(args.duration_ms) : null,
+    notes: args.notes ? String(args.notes) : null,
+    source: args.source ? String(args.source) : 'mcp',
+  });
+  if (!file) return { error: 'outcomes_record: write failed' };
+  return { ok: true, file };
+}
+
+// Mutating, gated: persist a research finding.
+
+export async function knowledgeAdd(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'knowledge_add requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  try {
+    const res = await addResearchFinding({
+      cwd,
+      slug: String(args.slug || ''),
+      topic: String(args.topic || ''),
+      body: String(args.body || ''),
+      confidence: args.confidence ? String(args.confidence) : 'inferred',
+      sources: Array.isArray(args.sources) ? args.sources : [],
+      ttlDays: Number.isFinite(args.ttl_days) ? Number(args.ttl_days) : undefined,
+    });
+    return { ok: true, path: res.path, bytes: res.bytes };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated: scaffold a draft profile.
+
+export function profileCreate(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_create requires confirm=true to scaffold files' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.id) return { error: 'profile_create requires id:string' };
+  try {
+    const res = createDraftProfile({
+      cwd,
+      id: String(args.id),
+      displayName: args.display_name ? String(args.display_name) : undefined,
+      seedRoles: Array.isArray(args.seed_roles) ? args.seed_roles.map(String) : [],
+      seedDepartments: Array.isArray(args.seed_departments) ? args.seed_departments : [],
+    });
+    return {
+      ok: true,
+      dir: res.dir,
+      briefPath: res.briefPath,
+      draftPath: res.draftPath,
+      personaPaths: res.personaPaths,
+      departmentPaths: res.departmentPaths,
+    };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated, destructive: archive a curated profile.
+
+export function profileArchive(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_archive requires confirm=true (destructive: moves files into archive/profiles/)' };
+  }
+  if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
+    return { error: 'profile_archive requires id:string and reason:string (>=8 chars)' };
+  }
+  try {
+    return { ok: true, ...archiveProfile({ id: String(args.id), reason: String(args.reason) }) };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Read-only: sandbox roster.
+
+export function sandboxList() {
+  return { sandboxes: listSandboxes() };
+}
+
+// Read-only: GraphRAG global query over the entity graph.
+
+export function knowledgeGraphAsk(args = {}) {
+  const cwd = cwdOf(args);
+  if (!args.query || typeof args.query !== 'string') {
+    return { error: 'knowledge_graph_ask requires query:string' };
+  }
+  const topK = Number.isFinite(args.top_k) ? Number(args.top_k) : 5;
+  const minSize = Number.isFinite(args.min_size) ? Number(args.min_size) : undefined;
+  return askGlobal({ query: String(args.query), rootDir: cwd, topK, ...(minSize !== undefined ? { minSize } : {}) });
+}
+
+// Read-only: learning dashboard mirror.
+
+export function learningStatus(args = {}) {
+  const cwd = cwdOf(args);
+
+  let observations = { total: 0, last24h: 0 };
+  try {
+    const idxPath = join(cwd, '.cx', 'observations', 'index.json');
+    if (existsSync(idxPath)) {
+      const idx = JSON.parse(readFileSync(idxPath, 'utf8'));
+      if (Array.isArray(idx)) {
+        const since = Date.now() - 24 * 60 * 60 * 1000;
+        observations = {
+          total: idx.length,
+          last24h: idx.filter((e) => Date.parse(e?.createdAt) >= since).length,
+        };
+      }
+    }
+  } catch { /* best effort */ }
+
+  let researchCount = 0;
+  try {
+    const dir = join(cwd, '.cx', 'knowledge', 'external', 'research');
+    if (existsSync(dir)) {
+      researchCount = readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+    }
+  } catch { /* best effort */ }
+
+  const profile = resolveActiveProfile(cwd);
+  const outcomes = readSummary(cwd) || { roles: {} };
+
+  return {
+    profile: { id: profile.id, displayName: profile.displayName ?? profile.id, custom: profile.custom === true },
+    observations,
+    research: { count: researchCount },
+    outcomes,
+  };
+}

package/lib/mcp/tools/workflow.mjs

@@ -96,6 +96,31 @@ export function workflowValidate(args) {
   return { cwd, ...result };
 }
 
+/**
+ * Validate a producer→consumer handoff against agents/contracts.json.
+ *
+ * Args:
+ *   producer    — agent or persona name producing the artifact
+ *   consumer    — agent or persona name receiving it
+ *   id          — optional contract id (overrides producer/consumer lookup)
+ *   artifact    — the handoff payload to validate
+ *   enforcement — 'warn' (default) or 'block'; 'block' returns ok:false on
+ *                 violation so the workflow can refuse to advance
+ *
+ * Returns { ok, status?, errors?, warnings?, contract } where status is set
+ * to 'BLOCKED_CONTRACT' on enforced violations.
+ */
+export async function workflowContractValidate(args) {
+  const { validateHandoff } = await import('../../contracts/validate.mjs');
+  return validateHandoff({
+    producer: args.producer,
+    consumer: args.consumer,
+    id: args.id,
+    artifact: args.artifact,
+    enforcement: args.enforcement || process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+  });
+}
+
 export function workflowImportPlan(args) {
   const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
   const markdown = args.markdown ?? '';

package/lib/mcp-catalog.json

@@ -55,21 +55,25 @@
       "id": "memory",
       "name": "Memory",
       "category": "optional",
-      "description": "cass-memory over HTTP. Persistent cross-session and cross-agent memory for decisions, findings, and handoffs.",
-      "type": "url",
-      "url": "http://127.0.0.1:8765/",
-      "env": {},
+      "description": "cass-memory persistent cross-session and cross-agent memory, fronted by the Construct stdio MCP bridge so editors get a full MCP handshake.",
+      "command": "node",
+      "args": [
+        "__CX_TOOLKIT_DIR__/lib/mcp/memory-bridge.mjs"
+      ],
+      "env": {
+        "CONSTRUCT_MEMORY_BRIDGE_URL": "http://127.0.0.1:__MEMORY_PORT__/"
+      },
       "requiredEnv": [],
       "setupModes": [
         "auto",
         "manual"
       ],
       "hostSupport": {
-        "claude": { "mode": "unsupported", "label": "construct-mcp (project .mcp.json)" },
-        "opencode": { "mode": "unsupported", "label": "construct-mcp (stdio)" },
-        "codex": { "mode": "unsupported", "label": "construct-mcp / local observation tools" }
+        "claude": { "mode": "managed" },
+        "opencode": { "mode": "managed" },
+        "codex": { "mode": "managed" }
       },
-      "setupNote": "Claude Code and Codex reject the cass-memory HTTP endpoint because `cm serve` skips the MCP `initialize` handshake. On Claude, memory tools (memory_search, memory_add_observations, memory_recent, memory_create_entities) are exposed through the project-local construct-mcp stdio server in .mcp.json. OpenCode does not support the cass-memory HTTP endpoint (SSE transport fails with 405) — use construct-mcp stdio server instead, which wraps memory tools correctly.",
+      "setupNote": "Memory is wired as a stdio MCP bridge (lib/mcp/memory-bridge.mjs). The bridge answers the MCP handshake locally (initialize, ping, notifications/initialized) and forwards tools/list, tools/call, resources/list, resources/read to cm at CONSTRUCT_MEMORY_BRIDGE_URL. cm itself never sees the handshake calls that v0.2.x cannot answer.",
       "usedBy": [
         "construct",
         "cx-docs-keeper",

package/lib/mcp-platform-config.mjs

@@ -48,13 +48,21 @@ function buildRemoteHeaders(mcpDef, resolvedValues) {
   return stripUnresolvedValues(resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues));
 }
 
+function withMemoryDefaults(id, values) {
+  if (id !== "memory") return values;
+  if (values.MEMORY_PORT) return values;
+  return { ...values, MEMORY_PORT: "8765" };
+}
+
 export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
+  const values = withMemoryDefaults(id, { CX_TOOLKIT_DIR: ROOT_DIR, ...resolvedValues });
+
   if (mcpDef.type === "url") {
-    const headers = buildRemoteHeaders(mcpDef, resolvedValues);
+    const headers = buildRemoteHeaders(mcpDef, values);
     const url =
-      id === "memory" && resolvedValues.MEMORY_PORT
-        ? `http://127.0.0.1:${resolvedValues.MEMORY_PORT}/`
-        : resolveTemplateString(mcpDef.url, resolvedValues);
+      id === "memory" && values.MEMORY_PORT
+        ? `http://127.0.0.1:${values.MEMORY_PORT}/`
+        : resolveTemplateString(mcpDef.url, values);
     return {
       type: "http",
       url,
@@ -62,19 +70,19 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
     };
   }
 
-  const env = buildLocalEnvironment(mcpDef, resolvedValues);
+  const env = buildLocalEnvironment(mcpDef, values);
   return {
     command: mcpDef.command,
-    args: resolveArgs(mcpDef.args, resolvedValues),
+    args: resolveArgs(mcpDef.args, values),
     ...(Object.keys(env).length > 0 ? { env } : {}),
   };
 }
 
 export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
-  const runtimeValues = {
+  const runtimeValues = withMemoryDefaults(id, {
     CX_TOOLKIT_DIR: ROOT_DIR,
     ...resolvedValues,
-  };
+  });
   const openCodeId = getOpenCodeMcpId(id);
 
   if (mcpDef.type === "url") {

package/lib/migrations/index.mjs

@@ -0,0 +1,106 @@
+/**
+ * lib/migrations/index.mjs — Schema migration registry and runner.
+ *
+ * Construct's machine-readable artifacts (agents/registry.json, contracts.json,
+ * role-manifests.json, .cx/config.json, profile JSON) carry an integer
+ * `version` field. When the installed binary's expected schema version is
+ * higher than the on-disk version, migrations apply in order. When the on-disk
+ * version is higher, the runner refuses to load and instructs the operator to
+ * upgrade.
+ *
+ * Each migration is a module under lib/migrations/ that exports:
+ *   - from: integer
+ *   - to: integer
+ *   - apply(artifactPath, options): Promise<{ changed, summary }>
+ *
+ * v1 is the baseline — no migration needed. The registry below is the contract
+ * between the installed binary and migration authors.
+ */
+
+import v1Baseline from './v1-baseline.mjs';
+
+const REGISTRY = [
+  v1Baseline,
+];
+
+export const CURRENT_SCHEMA_VERSION = Math.max(...REGISTRY.map((m) => m.to));
+
+/**
+ * Compute the migration path from `fromVersion` to CURRENT_SCHEMA_VERSION.
+ * Returns an array of migrations to apply in order, or null if no path exists.
+ */
+export function planMigrations(fromVersion, toVersion = CURRENT_SCHEMA_VERSION) {
+  if (fromVersion === toVersion) return [];
+  if (fromVersion > toVersion) return null;
+  const steps = [];
+  let cursor = fromVersion;
+  while (cursor < toVersion) {
+    const step = REGISTRY.find((m) => m.from === cursor);
+    if (!step) return null;
+    steps.push(step);
+    cursor = step.to;
+  }
+  return steps;
+}
+
+/**
+ * Apply a planned migration sequence. Each step receives the artifact path
+ * and any options. Returns a summary including every step's outcome.
+ *
+ * When dryRun is true, steps must not write to disk; they only report what
+ * they would change.
+ */
+export async function runMigrations({ artifactPath, fromVersion, toVersion = CURRENT_SCHEMA_VERSION, dryRun = false }) {
+  const plan = planMigrations(fromVersion, toVersion);
+  if (plan === null) {
+    return {
+      ok: false,
+      error: `no migration path from version ${fromVersion} to ${toVersion}`,
+      applied: [],
+    };
+  }
+  if (plan.length === 0) {
+    return { ok: true, applied: [], summary: 'no migrations needed' };
+  }
+
+  const applied = [];
+  for (const step of plan) {
+    try {
+      const result = await step.apply(artifactPath, { dryRun });
+      applied.push({ from: step.from, to: step.to, ...result });
+    } catch (err) {
+      return {
+        ok: false,
+        error: `migration ${step.from}→${step.to} failed: ${err.message}`,
+        applied,
+      };
+    }
+  }
+  return { ok: true, applied, summary: `applied ${applied.length} migration(s)` };
+}
+
+/**
+ * Check artifact compatibility. Returns:
+ *   { compatible: true }                              — versions match
+ *   { compatible: false, needsMigration: true,  ... } — on-disk is older
+ *   { compatible: false, needsUpgrade: true, ... }   — on-disk is newer
+ */
+export function checkCompatibility(artifactVersion, expected = CURRENT_SCHEMA_VERSION) {
+  if (artifactVersion === expected) return { compatible: true };
+  if (artifactVersion < expected) {
+    return {
+      compatible: false,
+      needsMigration: true,
+      fromVersion: artifactVersion,
+      toVersion: expected,
+      message: `artifact schema version ${artifactVersion} is older than expected ${expected}; run 'construct migrate'`,
+    };
+  }
+  return {
+    compatible: false,
+    needsUpgrade: true,
+    fromVersion: artifactVersion,
+    toVersion: expected,
+    message: `artifact schema version ${artifactVersion} is newer than this binary supports (${expected}); run 'construct upgrade'`,
+  };
+}

package/lib/migrations/v1-baseline.mjs

@@ -0,0 +1,33 @@
+/**
+ * lib/migrations/v1-baseline.mjs — No-op baseline migration.
+ *
+ * Marks v0 (pre-versioned artifacts) as compatible with v1 by stamping the
+ * artifact with `version: 1` when absent. Schema bumps after v1 will add new
+ * migrations rather than modifying this one.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+export default {
+  from: 0,
+  to: 1,
+  description: 'Stamp pre-versioned artifacts with version: 1 (no shape changes)',
+  async apply(artifactPath, { dryRun = false } = {}) {
+    if (!existsSync(artifactPath)) {
+      return { changed: false, summary: `${artifactPath}: not present (skip)` };
+    }
+    let data;
+    try { data = JSON.parse(readFileSync(artifactPath, 'utf8')); }
+    catch (err) { throw new Error(`failed to parse ${artifactPath}: ${err.message}`); }
+
+    if (data && typeof data === 'object' && data.version === 1) {
+      return { changed: false, summary: `${artifactPath}: already at v1` };
+    }
+
+    const next = { ...data, version: 1 };
+    if (!dryRun) {
+      writeFileSync(artifactPath, JSON.stringify(next, null, 2) + '\n');
+    }
+    return { changed: true, summary: `${artifactPath}: stamped version: 1` };
+  },
+};

package/lib/observation-store.mjs

@@ -19,6 +19,7 @@ import { embedSync as embedText } from './storage/embeddings-legacy.mjs';
 import { embedText as embedTextEngine } from './storage/embeddings-engine.mjs';
 import { VectorClient } from './storage/vector-client.mjs';
 import { withFileLockSync } from './storage/file-lock.mjs';
+import { ensureCxDir } from './project-init-shared.mjs';
 
 const OBS_DIR = '.cx/observations';
 const INDEX_FILE = 'index.json';
@@ -36,7 +37,10 @@ const VALID_CATEGORIES = new Set([
   'pattern', 'anti-pattern', 'dependency', 'decision', 'insight', 'session-summary',
 ]);
 
-function ensureDir(dir) {
+function ensureDir(dir, rootDir = null) {
+  // Preserves the construct context invariant: any code that creates a .cx/
+  // subdirectory also initializes context.md from the project template.
+  if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
@@ -91,6 +95,7 @@ function logCapDrop(rootDir, kind, dropped, total) {
   if (dropped <= 0) return;
   try {
     const logPath = path.join(rootDir, '.cx', 'observation-cap-warnings.jsonl');
+    ensureCxDir(rootDir);
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     const entry = JSON.stringify({
       ts: new Date().toISOString(),
@@ -105,7 +110,7 @@ function logCapDrop(rootDir, kind, dropped, total) {
 }
 
 function writeIndex(rootDir, entries) {
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX);
   if (entries.length > MAX_INDEX) {
     logCapDrop(rootDir, 'observation-index', entries.length - MAX_INDEX, entries.length);
@@ -124,7 +129,7 @@ function readVectors(rootDir) {
 }
 
 function writeVectors(rootDir, records) {
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   if (records.length > MAX_INDEX) {
     logCapDrop(rootDir, 'observation-vectors', records.length - MAX_INDEX, records.length);
   }
@@ -177,7 +182,7 @@ export async function addObservation(rootDir, {
   // Lock the per-store index so concurrent writers (CLI + hooks) cannot
   // corrupt the index/vectors JSON pair. The observation JSON file is
   // unique-per-id and doesn't need the lock; the shared structures do.
-  ensureDir(obsDir(rootDir));
+  ensureDir(obsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(obsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + '\n',

package/lib/outcomes/record.mjs

@@ -16,6 +16,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { withFileLockSync } from '../storage/file-lock.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const ROTATE_AT = 10_000;
 const MAX_NOTES = 500;
@@ -65,6 +66,7 @@ function countLines(file) {
 export function recordOutcome(cwd, payload) {
   if (!cwd || !payload || typeof payload.success !== 'boolean') return null;
   try {
+    ensureCxDir(cwd);
     fs.mkdirSync(outcomesDir(cwd), { recursive: true });
     const file = activeFile(cwd, payload.role);
 

package/lib/profiles/rebrand.mjs

@@ -0,0 +1,46 @@
+/**
+ * lib/profiles/rebrand.mjs — Profile-aware language helper.
+ *
+ * Each curated profile carries a `rebrand` block: how the active profile
+ * wants the intake queue and individual signal items named in user-facing
+ * surfaces (CLI output, daemon logs, session-start prelude). The helper
+ * centralises that lookup so every consumer goes through one path with
+ * safe defaults instead of hardcoding "intake queue" / "signal" / "intake".
+ *
+ * Defaults match the legacy strings so behaviour is unchanged for the rnd
+ * profile and for any environment where profile resolution fails.
+ */
+
+import { resolveActiveProfile } from './loader.mjs';
+
+export const DEFAULT_REBRAND = Object.freeze({
+  intakeQueueLabel: 'Intake queue',
+  signalNoun: 'signal',
+});
+
+/**
+ * Return the active profile's rebrand labels.
+ *
+ * @param {string} [rootDir] - project root where profile.json / construct.config.json live.
+ * @returns {{ intakeQueueLabel: string, signalNoun: string }}
+ *
+ * Returns defaults when `rootDir` is missing, when the profile cannot be
+ * loaded, or when the profile omits its `rebrand` block. Never throws.
+ */
+export function getRebrand(rootDir) {
+  if (!rootDir || typeof rootDir !== 'string') return { ...DEFAULT_REBRAND };
+  try {
+    const profile = resolveActiveProfile(rootDir);
+    const rb = profile?.rebrand;
+    if (!rb || typeof rb !== 'object') return { ...DEFAULT_REBRAND };
+    const intakeQueueLabel = typeof rb.intakeQueueLabel === 'string' && rb.intakeQueueLabel.trim()
+      ? rb.intakeQueueLabel.trim()
+      : DEFAULT_REBRAND.intakeQueueLabel;
+    const signalNoun = typeof rb.signalNoun === 'string' && rb.signalNoun.trim()
+      ? rb.signalNoun.trim()
+      : DEFAULT_REBRAND.signalNoun;
+    return { intakeQueueLabel, signalNoun };
+  } catch {
+    return { ...DEFAULT_REBRAND };
+  }
+}

package/lib/project-init-shared.mjs

@@ -235,6 +235,18 @@ Describe the current objective in one clear sentence.
 `;
 }
 
+export function ensureCxDir(rootDir) {
+  const cxDir = path.join(rootDir, '.cx');
+  const contextPath = path.join(cxDir, 'context.md');
+  if (!fs.existsSync(cxDir)) {
+    fs.mkdirSync(cxDir, { recursive: true });
+  }
+  if (!fs.existsSync(contextPath)) {
+    fs.writeFileSync(contextPath, buildContextMarkdown(), 'utf8');
+  }
+  return cxDir;
+}
+
 export function buildContextMarkdown() {
   return `<!--
 .cx/context.md — concise resumable project context for human and agent handoff.