@geraldmaron/construct 1.0.4 → 1.0.5

package/README.md

@@ -1,73 +1,78 @@
 # Construct
 
-> One AI interface. 28 specialists. Hard gates. Runs locally or deploys for teams.
+> Heads up. Construct is an open source project I started. I am not a developer. This is a side project. There may be bugs, there may be defects, but I'm building it to learn in public. If you'd like to contribute, please do.
 
-Construct is a deployable AI R&D operating system. You address one persona — `construct` — in Claude Code, OpenCode, Codex, Cursor, or Copilot. Behind that persona is a team of 28 specialists (architect, engineer, reviewer, QA, security, designer, …) under typed contracts and enforced gates. Sessions survive boundary changes via durable state in `.cx/`, beads, and the vector index. Construct runs locally for individual users (the default) and can be deployed centrally for shared team usage with shared memory, telemetry, queues, and policy.
+One AI interface. A team of specialists behind it. Hard gates. Runs locally, or deploys for teams.
 
-**Full docs:** [`geraldmaron.github.io/construct/v2/`](https://geraldmaron.github.io/construct/v2/) (Phase 1) · while the new docs site is rolling out, the legacy MkDocs site still serves the root URL.
+Construct sits on top of Claude Code, OpenCode, Codex, Cursor, and Copilot. You talk to one persona called `construct`. Behind it are 28 specialists (architect, engineer, reviewer, QA, security, designer, and more) under typed contracts and enforced gates. Sessions survive boundary changes via durable state in `.cx/`, beads, and a local vector index. Solo by default. Can deploy centrally for teams that want shared memory, telemetry, queues, and policy.
 
-## Getting Started
+The team and enterprise modes exist because I wanted to learn what shipping a real multi-tenant tool would look like. The project is still open source, the code is still public, and the bar is still "does this help me learn." Run it solo if that's all you need.
 
-### Step 1: Install CLI (one-time, per machine)
+Full docs: [`geraldmaron.github.io/construct/v2/`](https://geraldmaron.github.io/construct/v2/).
+
+## Getting started
+
+Install the CLI (once per machine):
 
 ```bash
 npm install -g @geraldmaron/construct
 ```
 
-### Step 2: Machine Setup (one-time, per machine)
-
-First time on a new machine, bootstrap local services. `construct install` can start local Postgres/pgvector via Docker; traces are written locally by default and remote telemetry export is optional:
+Bootstrap local services (once per machine):
 
 ```bash
 construct install --yes
-# Local services:
-#   Traces: .cx/traces/*.jsonl
-#   Postgres: postgresql://construct:construct@127.0.0.1:54329/construct
 ```
 
-### Step 3: Initialize Project (per project)
+Initialize a project:
 
 ```bash
 cd ~/your-project
 construct init --auto-start
 ```
 
-The postinstall hook stages `.construct/` and `.claude/` into your project, so hooks, agents, and slash commands are wired up automatically. Peers who clone your repo and run `npm install` get the same setup with no extra steps.
+Open your editor and talk to `@construct`. A walkthrough lives in `construct_guide.md` at your project root.
 
-Open your editor and address `@construct`. A friendly orientation lives in `construct_guide.md` at your project root.
+No Node? Try `brew install geraldmaron/construct/construct`. Cloning a project that already uses Construct? `npx -y @geraldmaron/construct init` wires it up.
 
-If you cloned a project that does not yet pin Construct, run `npx -y @geraldmaron/construct init` once to wire it up. No Node at all? `brew install geraldmaron/construct/construct`.
+[Five minute walkthrough](https://geraldmaron.github.io/construct/v2/docs/start).
 
-[Full 5-minute walkthrough →](https://geraldmaron.github.io/construct/v2/docs/start)
-
-## What you can do with it
+## What you can do
 
 | If you want to... | Read |
 |---|---|
-| Install + first task | [Start](https://geraldmaron.github.io/construct/v2/docs/start) |
-| Understand how it works | [Concepts → Architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) |
-| Pick a deployment mode | [Concepts → Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model) |
-| Drop a signal and triage it | [Concepts → Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage) |
-| Add a custom specialist | [Cookbook → Add a custom agent](https://geraldmaron.github.io/construct/v2/docs/cookbook/add-a-custom-agent) |
-| Fix a blocked commit or red CI | [Cookbook → Fix a policy violation](https://geraldmaron.github.io/construct/v2/docs/cookbook/fix-a-policy-violation) |
-| Plug in your own LLM | [Cookbook → Plug in your own LLM](https://geraldmaron.github.io/construct/v2/docs/cookbook/plug-in-your-own-llm) |
-| Deploy to AWS | [Cookbook → Deploy to AWS](https://geraldmaron.github.io/construct/v2/docs/cookbook/deploy-to-aws) |
-| Look up a CLI command | [Reference → CLI](https://geraldmaron.github.io/construct/v2/docs/reference/cli) |
-| Recover from an outage | [Operations → Troubleshooting](https://geraldmaron.github.io/construct/v2/docs/operations/troubleshooting) |
+| Install and run a first task | [Start](https://geraldmaron.github.io/construct/v2/docs/start) |
+| Understand how it works | [Architecture](https://geraldmaron.github.io/construct/v2/docs/concepts/architecture) |
+| Pick a deployment mode | [Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model) |
+| Drop a signal and triage it | [Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage) |
+| Add a custom specialist | [Add a custom agent](https://geraldmaron.github.io/construct/v2/docs/cookbook/add-a-custom-agent) |
+| Fix a blocked commit or red CI | [Fix a policy violation](https://geraldmaron.github.io/construct/v2/docs/cookbook/fix-a-policy-violation) |
+| Plug in your own LLM | [Plug in your own LLM](https://geraldmaron.github.io/construct/v2/docs/cookbook/plug-in-your-own-llm) |
+| Look up a CLI command | [CLI reference](https://geraldmaron.github.io/construct/v2/docs/reference/cli) |
 
 Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible providers.
 
-## Deployable: solo, team, or enterprise
+## Deployment modes
+
+Three modes. `solo` is the default and runs everything locally. Filesystem queue, local repo state, optional Postgres via Docker, local JSONL traces. If every cloud service goes down, you still work from `plan.md`, `.cx/context.md`, beads, git, and the local vector index.
 
-Construct has three deployment modes. `solo` (the default) runs everything locally — filesystem queue, local repo state, optional Postgres/Docker, and local JSONL traces — so if every cloud service goes down you still work from `plan.md`, `.cx/context.md`, beads, git, and the local vector index. `team` promotes the intake queue to Postgres with row-locked worker claims, shares memory across the team, runs workers in a Docker pool, centralizes telemetry through Langfuse-compatible, HTTP, or OTLP export, and routes MCP through a broker. `enterprise` adds tenant isolation, RBAC/ABAC scaffolding, isolated worker containers, signed MCP allowlists, and mandatory audit. Pick or change modes with `construct config mode [solo|team|enterprise]`. [Concepts → Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model).
+`team` promotes the intake queue to Postgres with row-locked worker claims. Shared memory, Docker worker pool, centralized telemetry, MCP through a broker.
+
+`enterprise` adds tenant isolation, RBAC and ABAC scaffolding, isolated worker containers, signed MCP allowlists, and mandatory audit.
+
+Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deployment model](https://geraldmaron.github.io/construct/v2/docs/concepts/deployment-model).
 
 ## Signals to R&D
 
-Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified into an R&D intake type — bug, user-signal, experiment, eval-finding, architecture, incident, security, requirement, research, ops, or legal-compliance — and assigned a primary owner persona with a recommended handoff chain. Inspect with `construct intake list / show <id>`, generate a task graph with `construct graph from-intake <id>`, and update node status with verifiable evidence as work progresses. The classifier is deterministic and runs in the daemon (no LLM); the agent in your editor handles the actual analysis. [Concepts → Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage).
+Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified into one of: bug, user-signal, experiment, eval-finding, architecture, incident, security, requirement, research, ops, legal-compliance. Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/v2/docs/concepts/intake-and-triage).
 
 ## Hard gates
 
-Every code mutation runs through enforcement: no secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places (write-time, commit-time, CI safety-net) and can only be bypassed with explicit env vars so every exception leaves an audit trail. [Concepts → Gates and enforcement](https://geraldmaron.github.io/construct/v2/docs/concepts/gates-and-enforcement).
+Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/v2/docs/concepts/gates-and-enforcement).
+
+## Learning loops
+
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.md`](./docs/concepts/learning-loops.md) for what's wired, what's coming, and how to turn pieces off.
 
 ## Core commands
 
@@ -83,7 +88,9 @@ Every code mutation runs through enforcement: no secrets committed, tests green,
 | `construct install` | Machine setup: install Docker, cm, and bootstrap config |
 | `construct intake` | View and process R&D intake queue |
 | `construct models` | Manage AI model assignments |
+| `construct profile` | Manage the active org profile and its lifecycle (draft, promote, archive, health) |
 | `construct recommendations` | View and manage artifact recommendations |
+| `construct sandbox` | Isolated tmpdir-based environment for QA / specialist dry-runs |
 | `construct status` | Show system health and credentials |
 | `construct stop` | Stop all running services |
 | `construct sync` | Sync agent adapters to AI tools |
@@ -101,6 +108,7 @@ Every code mutation runs through enforcement: no secrets committed, tests green,
 | `construct infer` | Infer schema from documents |
 | `construct ingest` | Convert documents to indexed markdown |
 | `construct integrations` | Check and manage external system connections |
+| `construct knowledge` | Query, index, or add to the project knowledge base |
 | `construct memory` | Inspect memory layer |
 | `construct reflect` | Capture improvement feedback |
 | `construct search` | Hybrid search across project state |
@@ -158,10 +166,10 @@ Every code mutation runs through enforcement: no secrets committed, tests green,
 
 ## For contributors
 
-- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — branch workflow, gates, review expectations.
-- [`CHANGELOG.md`](./CHANGELOG.md) — release history.
-- [`docs/concepts/architecture.md`](./docs/concepts/architecture.md) — canonical architecture (rendered on the docs site at [Concepts → Architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture)).
-- [`AGENTS.md`](./AGENTS.md) — agent operating contract.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
+- [`CHANGELOG.md`](./CHANGELOG.md). Release history.
+- [`docs/concepts/architecture.md`](./docs/concepts/architecture.md). Canonical architecture.
+- [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure
 
@@ -169,7 +177,7 @@ Every code mutation runs through enforcement: no secrets committed, tests green,
 ```text
 construct/
 ├── agents           Registry and generated platform adapter chains
-├── apps             User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)
+├── apps             User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)
 ├── bin              CLI entrypoint (`construct`)
 ├── commands         Command prompt assets
 ├── dashboard
@@ -180,6 +188,7 @@ construct/
 ├── lib              Core runtime: CLI, hooks, MCP, status, sync, workflow
 ├── personas         Persona prompt definitions
 ├── platforms
+├── profiles
 ├── providers
 ├── rules            Coding and quality standards
 ├── schemas
@@ -193,16 +202,16 @@ construct/
 
 ## Uninstall
 
-Run the uninstaller first, then drop the package:
+Run the uninstaller first, then remove the package:
 
 ```bash
 construct uninstall          # interactive; pick what to remove
 npm uninstall @geraldmaron/construct
 ```
 
-`construct uninstall` probes both project-scope (`.construct/`, the Construct-owned `.claude/agents/` + `.claude/commands/` files, hooks/mcpServers Construct added to `.claude/settings.json`) and machine-scope state (`~/.cx/`, `~/.construct/workspace/`, the embedding model cache, the local Postgres container). Auto-risk items are removed by default; ask-risk items (Postgres data, API keys, AGENTS.md/plan.md you may have edited) are skipped unless you opt in.
+`construct uninstall` finds both project state (`.construct/`, the Construct-owned files under `.claude/agents/` and `.claude/commands/`, hooks and mcpServers Construct added to `.claude/settings.json`) and machine state (`~/.cx/`, `~/.construct/workspace/`, the embedding model cache, the local Postgres container). Auto-risk items go by default. Ask-risk items (Postgres data, API keys, files you may have edited) are skipped unless you opt in.
 
-It never touches Docker itself, Homebrew CLIs like `cm`/`cass`, the pgvector image, or anything you've added to `.claude/settings.json` by hand. Those appear in the final summary as follow-ups you can run if you want.
+It will not touch Docker itself, Homebrew CLIs like `cm` and `cass`, the pgvector image, or anything you added to `.claude/settings.json` by hand. Those appear in the final summary as follow-ups.
 
 Useful flags:
 
@@ -210,8 +219,8 @@ Useful flags:
 construct uninstall --dry-run            # show the plan, change nothing
 construct uninstall --yes                # non-interactive, auto-risk only
 construct uninstall --yes --all          # non-interactive, everything
-construct uninstall --scope=project      # only this project; leave ~/.construct alone
-construct uninstall --keep-state         # only .construct/ + .claude/; keep .cx/, ~/.construct, Postgres
+construct uninstall --scope=project      # only this project, leave ~/.construct alone
+construct uninstall --keep-state         # only .construct/ and .claude/, keep .cx/, ~/.construct, Postgres
 ```
 
 ## License

package/bin/construct

@@ -186,14 +186,49 @@ function runNodeScript(scriptPath, args = [], extraEnv = {}) {
 async function cmdStatus() {
   const jsonOutput = restArgsCache.includes('--json');
   const status = await buildStatus({ rootDir: ROOT_DIR, cwd: process.cwd(), homeDir: HOME, env: process.env });
-  
+
   if (jsonOutput) {
     println(JSON.stringify(status, null, 2));
     return;
   }
-  
+
   println(formatStatusReport(status));
-  
+
+  // Append the learning-loops summary so the operator gets a single answer
+  // to "is this thing actually learning?" without remembering a second
+  // command. Cheap: just reads .cx/observations + .cx/outcomes summaries.
+  try {
+    const { resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    const { readSummary } = await import('../lib/outcomes/aggregate.mjs');
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const cwd = process.cwd();
+    const active = resolveActiveProfile(cwd);
+    const obsIdxPath = path.join(cwd, '.cx', 'observations', 'index.json');
+    let obsTotal = 0;
+    let obs24h = 0;
+    if (fs.existsSync(obsIdxPath)) {
+      const idx = JSON.parse(fs.readFileSync(obsIdxPath, 'utf8'));
+      obsTotal = idx.length;
+      const since = Date.now() - 24 * 60 * 60 * 1000;
+      obs24h = idx.filter((e) => Date.parse(e.createdAt) >= since).length;
+    }
+    const researchDir = path.join(cwd, '.cx', 'knowledge', 'external', 'research');
+    const researchCount = fs.existsSync(researchDir)
+      ? fs.readdirSync(researchDir).filter((f) => f.endsWith('.md')).length
+      : 0;
+    const summary = readSummary(cwd);
+    const outcomeRoles = summary?.roles ? Object.keys(summary.roles).length : 0;
+
+    println('');
+    println('Learning loops');
+    println('──────────────');
+    println(`  Profile          ${active.id} (${active.displayName || ''})`);
+    println(`  Observations     ${obsTotal} total, ${obs24h} in last 24h`);
+    println(`  Research files   ${researchCount}`);
+    println(`  Outcome roles    ${outcomeRoles}`);
+    println(`  Detail:          npm run learning:status`);
+  } catch { /* best-effort surface; never block status */ }
 }
 
 async function cmdShow() {
@@ -3233,6 +3268,27 @@ async function cmdHook(args) {
 const [command, ...rest] = process.argv.slice(2);
 const restArgsCache = rest;
 
+// Parse `--key=value` and repeatable `--source-url=<url>` for `construct knowledge add`.
+function parseKnowledgeAddArgs(args) {
+  const opts = { slug: null, topic: null, confidence: 'inferred', sources: [] };
+  for (const arg of args) {
+    if (arg.startsWith('--slug=')) opts.slug = arg.slice('--slug='.length);
+    else if (arg.startsWith('--topic=')) opts.topic = arg.slice('--topic='.length);
+    else if (arg.startsWith('--confidence=')) opts.confidence = arg.slice('--confidence='.length);
+    else if (arg.startsWith('--source-url=')) opts.sources.push({ url: arg.slice('--source-url='.length) });
+    else if (arg.startsWith('--source=')) { /* tag, ignored for now */ }
+  }
+  return opts;
+}
+
+// Read all of stdin as a UTF-8 string. Returns '' if nothing was piped.
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  return raw;
+}
+
 const handlers = new Map([
   // Core
   ['dev', cmdUp],
@@ -3268,6 +3324,24 @@ const handlers = new Map([
   ['handoffs', cmdHandoffs],
   ['headhunt', cmdHeadhunt],
   ['init', cmdInit],
+  ['drop', async (args) => {
+    const { runDropCli } = await import('../lib/drop.mjs');
+    return runDropCli(args, { cwd: process.cwd(), env: process.env });
+  }],
+  ['docs', async (args) => {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+      println('Usage: construct docs <check|verify|update|site>');
+      return;
+    }
+    const rest = args.slice(1);
+    if (sub === 'verify') return cmdDocsVerify(rest);
+    if (sub === 'update') return cmdDocsUpdate(rest);
+    if (sub === 'check') return cmdDocsCheck(rest);
+    if (sub === 'site') return cmdDocsSite();
+    errorln(`Unknown docs subcommand: ${sub}. Available: check, verify, update, site`);
+    process.exit(1);
+  }],
   ['docs:verify', cmdDocsVerify],
   ['init:update', cmdInitUpdate],
   ['models', cmdModels],
@@ -3833,7 +3907,185 @@ const handlers = new Map([
       }
       return;
     }
-    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index`);
+    if (sub === 'add') {
+      const opts = parseKnowledgeAddArgs(args.slice(1));
+      if (!opts.slug || !opts.topic) {
+        errorln('Usage: construct knowledge add --source=research --slug=<id> --topic="..." [--confidence=confirmed|inferred|weak] [--source-url=<url>] (body on stdin)');
+        process.exit(1);
+      }
+      const body = await readStdin();
+      if (!body || body.trim().length < 10) {
+        errorln('construct knowledge add: stdin body is empty or too short');
+        process.exit(1);
+      }
+      const { addResearchFinding } = await import('../lib/knowledge/research-store.mjs');
+      try {
+        const { path: outPath, bytes } = await addResearchFinding({
+          cwd: process.cwd(),
+          slug: opts.slug,
+          topic: opts.topic,
+          body,
+          confidence: opts.confidence,
+          sources: opts.sources,
+        });
+        process.stdout.write(`✓ wrote ${outPath} (${bytes} bytes)\n`);
+        return;
+      } catch (err) {
+        errorln(`construct knowledge add: ${err.message}`);
+        process.exit(1);
+      }
+    }
+    errorln(`Unknown knowledge subcommand: ${sub}. Available: trends, index, add`);
+    process.exit(1);
+  }],
+  ['sandbox', async (args) => {
+    const sub = args[0] || 'create';
+    const { createSandbox, listSandboxes, deleteSandbox, pruneSandboxes } = await import('../lib/sandbox.mjs');
+    if (sub === 'create') {
+      const profileArg = args.find((a) => a.startsWith('--profile='));
+      const profile = profileArg ? profileArg.split('=')[1] : null;
+      const { id, path: p } = createSandbox({ profile });
+      process.stdout.write(`✓ created sandbox ${id}\n  path: ${p}\n`);
+      if (profile) process.stdout.write(`  profile: ${profile}\n`);
+      return;
+    }
+    if (sub === 'list') {
+      const all = listSandboxes();
+      if (all.length === 0) { process.stdout.write('  (no sandboxes)\n'); return; }
+      for (const s of all) process.stdout.write(`  ${s.id.padEnd(30)}  ${s.path}\n`);
+      return;
+    }
+    if (sub === 'delete') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct sandbox delete <id>'); process.exit(1); }
+      process.stdout.write(deleteSandbox(id) ? `✓ removed ${id}\n` : `not found: ${id}\n`);
+      return;
+    }
+    if (sub === 'prune') {
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const days = daysArg ? Number(daysArg.split('=')[1]) || 7 : 7;
+      const removed = pruneSandboxes({ olderThanDays: days });
+      process.stdout.write(`✓ pruned ${removed} sandbox${removed === 1 ? '' : 'es'} older than ${days} day${days === 1 ? '' : 's'}\n`);
+      return;
+    }
+    errorln(`Unknown sandbox subcommand: ${sub}. Available: create, list, delete, prune`);
+    process.exit(1);
+  }],
+  ['profile', async (args) => {
+    const sub = args[0] || 'show';
+    const { listProfiles, loadProfile, resolveActiveProfile } = await import('../lib/profiles/loader.mjs');
+    if (sub === 'list') {
+      for (const id of listProfiles()) {
+        const p = loadProfile(id);
+        process.stdout.write(`  ${id.padEnd(14)} ${p?.displayName || ''}\n`);
+      }
+      return;
+    }
+    if (sub === 'show') {
+      const active = resolveActiveProfile(process.cwd());
+      process.stdout.write(JSON.stringify({
+        id: active.id,
+        displayName: active.displayName,
+        tagline: active.tagline,
+        roles: active.roles?.length || 0,
+        intakeTypes: active.intake?.types?.length || 0,
+      }, null, 2) + '\n');
+      return;
+    }
+    if (sub === 'set') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct profile set <id>'); process.exit(1); }
+      const target = loadProfile(id);
+      if (!target) {
+        errorln(`Unknown profile: ${id}. Available: ${listProfiles().join(', ')}`);
+        process.exit(1);
+      }
+      const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('../lib/config/project-config.mjs');
+      const fsMod = await import('node:fs');
+      const pathMod = await import('node:path');
+      const found = findProjectConfigPath(process.cwd());
+      const cfgPath = found || pathMod.join(process.cwd(), PROJECT_CONFIG_FILENAME);
+      const cfg = found ? (loadProjectConfig(process.cwd()) || { version: 1 }) : { version: 1 };
+      cfg.profile = id;
+      writeProjectConfig(cfgPath, cfg, { validate: true });
+      process.stdout.write(`✓ profile set to ${id} (${target.displayName})\n`);
+      return;
+    }
+    if (sub === 'create') {
+      const id = args[1];
+      if (!id) {
+        errorln('Usage: construct profile create <id> [--display="..."] [--role=<id>...] [--department=<id>:<displayName>...]');
+        process.exit(1);
+      }
+      const displayArg = args.find((a) => a.startsWith('--display='));
+      const displayName = displayArg ? displayArg.split('=')[1] : id;
+      const seedRoles = args
+        .filter((a) => a.startsWith('--role='))
+        .map((a) => a.slice('--role='.length))
+        .filter(Boolean);
+      const seedDepartments = args
+        .filter((a) => a.startsWith('--department='))
+        .map((a) => a.slice('--department='.length))
+        .map((spec) => {
+          const [deptId, deptDisplay] = spec.split(':');
+          return { id: deptId, displayName: deptDisplay || deptId };
+        });
+      const { createDraftProfile } = await import('../lib/profiles/lifecycle.mjs');
+      try {
+        const result = createDraftProfile({ cwd: process.cwd(), id, displayName, seedRoles, seedDepartments });
+        const pathMod = await import('node:path');
+        process.stdout.write(`✓ draft created for ${id}\n`);
+        process.stdout.write(`  brief:        ${pathMod.relative(process.cwd(), result.briefPath)}\n`);
+        process.stdout.write(`  draft:        ${pathMod.relative(process.cwd(), result.draftPath)}\n`);
+        if (result.personaPaths.length) process.stdout.write(`  personas:     ${result.personaPaths.length} scaffold(s) under personas/\n`);
+        if (result.departmentPaths.length) process.stdout.write(`  departments:  ${result.departmentPaths.length} charter(s) under departments/\n`);
+        process.stdout.write(`\nNext steps (in order, per docs/concepts/profile-lifecycle.md):\n`);
+        process.stdout.write(`  1. Discover: dispatch cx-ux-researcher to fill personas/<role>.md from interviews + primary sources.\n`);
+        process.stdout.write(`  2. Frame:    dispatch cx-product-manager to fill departments/<dept>.md charters and the intake taxonomy in profile.json.\n`);
+        process.stdout.write(`  3. Architect: dispatch cx-architect to reconcile role reuse vs new, and to populate departments[].\n`);
+        process.stdout.write(`  4. Validate: dispatch cx-evaluator to run persona-eval and classifier-eval against representative signals.\n`);
+        return;
+      } catch (err) {
+        errorln(err.message);
+        process.exit(1);
+      }
+    }
+    if (sub === 'drafts') {
+      const { listDrafts } = await import('../lib/profiles/lifecycle.mjs');
+      const drafts = listDrafts(process.cwd());
+      if (drafts.length === 0) { process.stdout.write('  (no drafts)\n'); return; }
+      for (const d of drafts) {
+        const flags = [d.hasBrief ? 'brief' : null, d.hasProfile ? 'profile' : null].filter(Boolean).join(', ');
+        process.stdout.write(`  ${d.id.padEnd(20)} ${flags}\n`);
+      }
+      return;
+    }
+    if (sub === 'archive') {
+      const id = args[1];
+      const reasonArg = args.find((a) => a.startsWith('--reason='));
+      const reason = reasonArg ? reasonArg.split('=')[1] : '';
+      if (!id) { errorln('Usage: construct profile archive <id> --reason="..."'); process.exit(1); }
+      const { archiveProfile } = await import('../lib/profiles/lifecycle.mjs');
+      try {
+        const { archived } = archiveProfile({ id, reason });
+        process.stdout.write(`✓ archived ${id} to ${archived}\n`);
+        return;
+      } catch (err) {
+        errorln(err.message);
+        process.exit(1);
+      }
+    }
+    if (sub === 'health') {
+      const id = args[1];
+      if (!id) { errorln('Usage: construct profile health <id> [--days=N]'); process.exit(1); }
+      const daysArg = args.find((a) => a.startsWith('--days='));
+      const windowDays = daysArg ? Number(daysArg.split('=')[1]) || 30 : 30;
+      const { profileHealth } = await import('../lib/profiles/lifecycle.mjs');
+      const report = profileHealth(process.cwd(), id, { windowDays });
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+      return;
+    }
+    errorln(`Unknown profile subcommand: ${sub}. Available: list, show, set, create, drafts, archive, health`);
     process.exit(1);
   }],
 ]);

package/commands/understand/research.md

@@ -1,10 +1,10 @@
 <!--
-commands/understand/research.md — Research a topic — verify facts from primary sources, separate evidence from inference
+commands/understand/research.md. Research a topic. Verify facts from primary sources, separate evidence from inference.
 
-Research a topic — verify facts from primary sources, separate evidence from inference
+Research a topic. Verify facts from primary sources, separate evidence from inference.
 -->
 ---
-description: Research a topic — verify facts from primary sources, separate evidence from inference
+description: Research a topic. Verify facts from primary sources, separate evidence from inference.
 ---
 
 You are Construct. Research: $ARGUMENTS
@@ -20,3 +20,5 @@ Method:
 For each finding: source, date, confidence (confirmed / inferred / weak signal).
 
 Output: FINDINGS (with citations) | INFERENCES (labeled) | GAPS | RECOMMENDATION
+
+Persistence: after producing the output, run `construct knowledge add --source=research --slug=<topic-slug> --topic="<one-line topic>" --confidence=<confirmed|inferred|weak>` and pass the FINDINGS+INFERENCES+GAPS+RECOMMENDATION block on stdin. The store writes a frontmatter-stamped markdown file under `.cx/knowledge/external/research/` and indexes it for future hybrid search. Pass `--source-url=<url>` repeatedly for each cited source (required when confidence=confirmed).

package/lib/auto-docs.mjs

@@ -71,7 +71,7 @@ function buildCoreDocsContract() {
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
     '| `docs/concepts/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
-    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed — durable work belongs in the tracker (Beads or external).',
+    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
     'Tracker hierarchy: external tracker (prefer Beads) for durable work, `plan.md` for the local working plan, and cass-memory via MCP `memory` for cross-session recall.',
     '',
@@ -82,7 +82,7 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',

package/lib/cli-commands.mjs

@@ -128,6 +128,50 @@ export const CLI_COMMANDS = [
       { name: 'search <query>', desc: 'Search customer profiles by name/alias' },
     ],
   },
+  {
+    name: 'knowledge',
+    emoji: '🧠',
+    category: 'Work',
+    core: false,
+    description: 'Query, index, or add to the project knowledge base',
+    usage: 'construct knowledge trends|index|add',
+    subcommands: [
+      { name: 'trends', desc: 'Show trend report across observations and artifacts' },
+      { name: 'index', desc: 'Rebuild the local RAG corpus over .cx/ artifacts' },
+      { name: 'add --source=research --slug=<id> --topic="..." [--source-url=<url>]', desc: 'Persist a research finding into .cx/knowledge/external/research/' },
+    ],
+  },
+  {
+    name: 'sandbox',
+    emoji: '🧪',
+    category: 'Core',
+    core: true,
+    description: 'Isolated tmpdir-based environment for QA / specialist dry-runs',
+    usage: 'construct sandbox create|list|delete|prune [--profile=<id>]',
+    subcommands: [
+      { name: 'create [--profile=<id>]', desc: 'Create a new sandbox under ~/.cx/sandboxes/' },
+      { name: 'list', desc: 'List existing sandboxes, newest first' },
+      { name: 'delete <id>', desc: 'Remove one sandbox by id' },
+      { name: 'prune [--days=N]', desc: 'Remove sandboxes older than N days (default 7)' },
+    ],
+  },
+  {
+    name: 'profile',
+    emoji: '🧭',
+    category: 'Core',
+    core: true,
+    description: 'Manage the active org profile and its lifecycle (draft, promote, archive, health)',
+    usage: 'construct profile show|list|set|create|drafts|archive|health',
+    subcommands: [
+      { name: 'show', desc: 'Show the active profile' },
+      { name: 'list', desc: 'List curated profiles' },
+      { name: 'set <id>', desc: 'Switch the active profile (writes construct.config.json)' },
+      { name: 'create <id> [--display="..."]', desc: 'Scaffold a draft profile + requirements brief under .cx/profiles/draft-<id>/' },
+      { name: 'drafts', desc: 'List in-progress draft profiles' },
+      { name: 'archive <id> --reason="..."', desc: 'Move a curated profile into archive/profiles/<id>/' },
+      { name: 'health <id> [--days=N]', desc: 'Per-profile observation + outcome rollup' },
+    ],
+  },
   {
     name: 'workspace',
     emoji: '🏢',

package/lib/comment-lint.mjs

@@ -42,7 +42,13 @@ function requiresHeader(rel) {
   if (rel.startsWith('lib/server/static/')) {
     return { required: false, type: null };
   }
-  const type = (jsMatch && ext !== '.html') ? 'js' : (jsMatch || mdMatch) ? 'md' : null;
+  // Markdown files always get markdown-style headers, even if the directory
+  // glob (e.g. ^tests/) primarily targets JS sources. Without this, .md docs
+  // co-located with .mjs tests were forced into /** */ format.
+  let type;
+  if (ext === '.md') type = mdMatch || jsMatch ? 'md' : null;
+  else if (jsMatch && ext !== '.html') type = 'js';
+  else type = (jsMatch || mdMatch) ? 'md' : null;
   return { required: jsMatch || mdMatch, type };
 }
 

package/lib/config/schema.mjs

@@ -20,6 +20,7 @@ export const CONFIG_SCHEMA_VERSION = 1;
 
 export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
+export const DEFAULT_PROFILE_ID = 'rnd';
 
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
@@ -31,6 +32,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     tenantId: null,
   }),
   providers: Object.freeze({}),
+  profile: DEFAULT_PROFILE_ID,
   autoEmbed: false,
   telemetry: Object.freeze({
     enabled: true,
@@ -77,6 +79,7 @@ export const FIELD_RULES = {
     },
   },
   providers: { type: 'object', required: false },
+  profile: { type: 'string', required: false, maxLength: 40 },
   autoEmbed: { type: 'boolean', required: false },
   telemetry: {
     type: 'object',