nexarch 0.11.0 → 0.11.1

package/README.md

@@ -25,6 +25,26 @@ npx nexarch setup
 | `nexarch init-agent [--json] [--strict] [--agent-id <id>] [--redact-hostname]` | Run onboarding handshake and mandatory `agent` entity registration in graph |
 | `nexarch init-agent --bind-to-external-key <key> [--bind-relationship-type <code>]` | Optionally bind the agent node to an existing graph external key |
 | `nexarch init-agent` (default behavior) | Also upserts technology component entities (host, OS, Node.js runtime) and links them to the agent |
+| `nexarch agent identify ...` | Submit provider/model/client identity metadata to complete agent profile enrichment |
+
+## Bootstrap flow after `init-agent`
+
+`nexarch init-agent` writes a bootstrap file at:
+
+```sh
+~/.nexarch/agent-bootstrap.md
+```
+
+That file contains a pre-filled `npx nexarch agent identify ...` command template.
+The current workflow is:
+
+1. run `npx nexarch init-agent`
+2. open `~/.nexarch/agent-bootstrap.md`
+3. copy the generated `npx nexarch agent identify ...` template
+4. fill in the real provider/model/client details
+5. run the completed command
+
+Do not assume an `npx nexarch agent prompt` command exists unless/until it is explicitly implemented and documented.
 
 ## Company context behavior
 

package/dist/commands/applied-policies.js

@@ -21,14 +21,14 @@ export async function appliedPolicies(args) {
     const asJson = parseFlag(args, "--json");
     const showMarkdown = parseFlag(args, "--markdown");
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch applied-policies [--pack <packCode>] [--markdown] [--json]
-
-Options:
-  --pack <code>     Filter to a specific policy pack code
-  --markdown        Include full document markdown in human output
-  --json            Print JSON response (always includes markdown)
+        console.log(`
+Usage:
+  nexarch applied-policies [--pack <packCode>] [--markdown] [--json]
+
+Options:
+  --pack <code>     Filter to a specific policy pack code
+  --markdown        Include full document markdown in human output
+  --json            Print JSON response (always includes markdown)
 `);
         return;
     }

package/dist/commands/check-in.js

@@ -40,49 +40,82 @@ export async function checkIn(args) {
     const agentKey = agentKeyArg ?? identity.agentKey;
     if (!agentKey) {
         if (asJson) {
-            process.stdout.write(JSON.stringify({ commands: [], reason: "no-agent-key" }) + "\n");
+            process.stdout.write(JSON.stringify({ commands: [], draftApplications: [], reason: "no-agent-key" }) + "\n");
         }
         else {
             console.log("No agent key found. Pass --agent-key or run nexarch init-agent first.");
         }
         return;
     }
-    const raw = await callMcpTool("nexarch_claim_command", {
-        agentRef: agentKey,
-        agentKey,
-        companyId: creds.companyId,
-    }, { companyId: creds.companyId });
+    const [raw, draftRaw] = await Promise.all([
+        callMcpTool("nexarch_claim_command", {
+            agentRef: agentKey,
+            agentKey,
+            companyId: creds.companyId,
+        }, { companyId: creds.companyId }),
+        callMcpTool("nexarch_list_entities", {
+            companyId: creds.companyId,
+            entityTypeCode: "application",
+            status: "draft",
+        }, { companyId: creds.companyId }),
+    ]);
     const result = parseToolText(raw);
+    const draftResult = parseToolText(draftRaw);
+    const draftApplications = draftResult.entities ?? [];
     if (asJson) {
-        process.stdout.write(JSON.stringify(result) + "\n");
+        process.stdout.write(JSON.stringify({ ...result, draftApplications }) + "\n");
         return;
     }
     const commands = result.commands ?? [];
-    if (commands.length === 0) {
+    if (commands.length === 0 && draftApplications.length === 0) {
         console.log("No pending application-target commands found.");
+        console.log("No applications in draft state.");
         return;
     }
-    console.log("\nPending application-target commands (preview only; nothing claimed):");
-    console.log(`Company scope is resolved server-side from companyId=${creds.companyId}.`);
-    if (identity.companyId && identity.companyId !== creds.companyId) {
-        console.log(`Note: local identity companyId ${identity.companyId} differs from current credentials companyId ${creds.companyId}.`);
+    if (commands.length > 0) {
+        console.log("\nPending application-target commands (preview only; nothing claimed):");
+        console.log(`Company scope is resolved server-side from companyId=${creds.companyId}.`);
+        if (identity.companyId && identity.companyId !== creds.companyId) {
+            console.log(`Note: local identity companyId ${identity.companyId} differs from current credentials companyId ${creds.companyId}.`);
+        }
+        for (const cmd of commands) {
+            const claimable = cmd.claimable ? "yes" : "no";
+            const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_not_found_for_company");
+            console.log(`\n- ID         : ${cmd.id}`);
+            console.log(`  Type       : ${cmd.command_type}`);
+            console.log(`  Target     : ${cmd.target_entity_key ?? "(none)"}`);
+            console.log(`  Priority   : ${cmd.priority}`);
+            console.log(`  Claimable  : ${claimable} (${reason})`);
+            if (cmd.command_type_version != null)
+                console.log(`  Type ver   : ${cmd.command_type_version}`);
+            if (cmd.resolved_runtime_handler)
+                console.log(`  Runtime    : ${cmd.resolved_runtime_handler}`);
+            if (cmd.claimable) {
+                console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"`);
+            }
+        }
+        console.log("\nTo validate an application target is accessible in Nexarch before claiming:");
+        console.log("  npx nexarch policy-controls --entity <application:key> --json");
+    }
+    else {
+        console.log("No pending application-target commands found.");
     }
-    for (const cmd of commands) {
-        const claimable = cmd.claimable ? "yes" : "no";
-        const reason = cmd.claimReason ?? (cmd.claimable ? "application_access_confirmed" : "application_not_found_for_company");
-        console.log(`\n- ID         : ${cmd.id}`);
-        console.log(`  Type       : ${cmd.command_type}`);
-        console.log(`  Target     : ${cmd.target_entity_key ?? "(none)"}`);
-        console.log(`  Priority   : ${cmd.priority}`);
-        console.log(`  Claimable  : ${claimable} (${reason})`);
-        if (cmd.command_type_version != null)
-            console.log(`  Type ver   : ${cmd.command_type_version}`);
-        if (cmd.resolved_runtime_handler)
-            console.log(`  Runtime    : ${cmd.resolved_runtime_handler}`);
-        if (cmd.claimable) {
-            console.log(`  Claim cmd  : npx nexarch command-claim --id "${cmd.id}"`);
+    if (draftApplications.length > 0) {
+        const count = draftApplications.length;
+        console.log(`\n--- Draft applications (${count}) ---`);
+        console.log(`${count === 1 ? "There is 1 application" : `There are ${count} applications`} in draft state.` +
+            " Ask the user if they would like to review and instantiate any of them.");
+        for (const app of draftApplications) {
+            const subtype = app.entitySubtypeCode ? ` [${app.entitySubtypeCode}]` : "";
+            const key = app.externalKey ? ` (${app.externalKey})` : "";
+            console.log(`\n  Name    : ${app.name}${subtype}${key}`);
+            if (app.description)
+                console.log(`  Desc    : ${app.description}`);
+            console.log(`  ID      : ${app.id}`);
+            console.log(`  Instantiate: npx nexarch proposals start --id "${app.id}"`);
         }
+        console.log("\nTo scaffold a draft application into a local project:");
+        console.log("  npx nexarch proposals start --id <applicationId>");
+        console.log("  npx nexarch proposals start --id <applicationId> --dir <path> --non-interactive");
     }
-    console.log("\nTo validate an application target is accessible in Nexarch before claiming:");
-    console.log("  npx nexarch policy-controls --entity <application:key> --json");
 }

package/dist/commands/governance-summary.js

@@ -11,12 +11,12 @@ function parseToolText(result) {
 export async function governanceSummary(args) {
     const asJson = parseFlag(args, "--json");
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch governance-summary [--json]
-
-Returns review queue counts, graph stats, and a per-application policy
-audit rollup (latest run status, pass/partial/fail counts).
+        console.log(`
+Usage:
+  nexarch governance-summary [--json]
+
+Returns review queue counts, graph stats, and a per-application policy
+audit rollup (latest run status, pass/partial/fail counts).
 `);
         return;
     }

package/dist/commands/init-project.js

@@ -168,13 +168,65 @@ function readSvnRepositoryUrl(dir) {
         return null;
     }
 }
+function isLocalOnlyUrl(value) {
+    if (!value)
+        return true;
+    try {
+        const u = new URL(value);
+        const host = u.hostname.toLowerCase();
+        if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1")
+            return true;
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function readGitRemoteCandidates(dir) {
+    const remotes = (safeExec("git", ["remote"], dir) ?? "")
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const names = remotes.length > 0 ? remotes : ["origin"];
+    const candidates = [];
+    for (const name of names) {
+        const value = safeExec("git", ["remote", "get-url", name], dir)
+            ?? safeExec("git", ["config", "--get", `remote.${name}.url`], dir);
+        if (value)
+            candidates.push(value);
+    }
+    return Array.from(new Set(candidates));
+}
+function choosePreferredRepositoryRef(candidates) {
+    if (candidates.length === 0)
+        return null;
+    const scored = candidates.map((rawRef, index) => {
+        const url = normalizeRepoUrl(rawRef);
+        const provider = inferProvider(url ?? rawRef);
+        const hostedProvider = provider !== "unknown";
+        const localOnly = isLocalOnlyUrl(url);
+        const score = [
+            hostedProvider ? 1 : 0,
+            !localOnly && Boolean(url) ? 1 : 0,
+            index === 0 ? 1 : 0,
+        ];
+        return { rawRef, score };
+    });
+    scored.sort((a, b) => {
+        for (let i = 0; i < a.score.length; i += 1) {
+            if (a.score[i] !== b.score[i])
+                return b.score[i] - a.score[i];
+        }
+        return 0;
+    });
+    return scored[0]?.rawRef ?? null;
+}
 function detectSourceRepository(dir) {
     let rawRef = null;
     let vcsType = "unknown";
-    // Prefer git when present.
+    // Prefer git when present, and prefer hosted remotes over local-only URLs.
     if (existsSync(join(dir, ".git"))) {
-        rawRef = safeExec("git", ["remote", "get-url", "origin"], dir)
-            ?? safeExec("git", ["config", "--get", "remote.origin.url"], dir);
+        rawRef = choosePreferredRepositoryRef(readGitRemoteCandidates(dir));
         if (rawRef)
             vcsType = "git";
     }

package/dist/commands/policy-audit-results.js

@@ -20,15 +20,15 @@ function parseToolText(result) {
 export async function policyAuditResults(args) {
     const asJson = parseFlag(args, "--json");
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch policy-audit-results --entity <applicationEntityRef> [--limit <1-10>] [--json]
-
-Options:
-  --entity <key>      Required application reference (e.g. application:my-service).
-                      Aliases: --entity-ref, --application-ref, --application-key
-  --limit <n>         Number of most recent runs to return (default 1, max 10)
-  --json              Print JSON response
+        console.log(`
+Usage:
+  nexarch policy-audit-results --entity <applicationEntityRef> [--limit <1-10>] [--json]
+
+Options:
+  --entity <key>      Required application reference (e.g. application:my-service).
+                      Aliases: --entity-ref, --application-ref, --application-key
+  --limit <n>         Number of most recent runs to return (default 1, max 10)
+  --json              Print JSON response
 `);
         return;
     }

package/dist/commands/proposals-start.js

@@ -0,0 +1,589 @@
+import process from "process";
+import * as readline from "node:readline/promises";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+function parseToolText(result) {
+    const text = result.content?.[0]?.text ?? "{}";
+    return JSON.parse(text);
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "application";
+}
+function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+function isDirectoryEmpty(path) {
+    if (!existsSync(path))
+        return true;
+    const stat = statSync(path);
+    if (!stat.isDirectory())
+        return false;
+    return readdirSync(path).length === 0;
+}
+function isDirectoryPath(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+function trimText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function formatBulletList(values) {
+    if (values.length === 0)
+        return "- None recorded";
+    return values.map((value) => `- ${value}`).join("\n");
+}
+function safeJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+async function promptChoice(proposals) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("\nProposed applications:");
+        proposals.forEach((proposal, index) => {
+            console.log(`  ${index + 1}) ${proposal.name}${proposal.entitySubtypeCode ? ` [${proposal.entitySubtypeCode}]` : ""}`);
+            if (proposal.description)
+                console.log(`     ${proposal.description}`);
+        });
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const answer = (await rl.question("\nChoose a proposal to start: ")).trim();
+            const pick = Number(answer);
+            if (Number.isFinite(pick) && pick >= 1 && pick <= proposals.length)
+                return proposals[pick - 1];
+            console.log(`Please enter a number between 1 and ${proposals.length}.`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirm(promptText, defaultYes = true) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return defaultYes;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(promptText)).trim().toLowerCase();
+        if (!answer)
+            return defaultYes;
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptValue(promptText, fallback) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return fallback;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(promptText)).trim();
+        return answer || fallback;
+    }
+    finally {
+        rl.close();
+    }
+}
+function normalizeForMatch(value) {
+    return (value ?? "").trim().toLowerCase();
+}
+function inferStackTemplate(proposal) {
+    const subtype = normalizeForMatch(proposal.application.entitySubtypeCode);
+    const haystack = [
+        proposal.application.name,
+        proposal.application.description,
+        proposal.application.entitySubtypeCode,
+        ...proposal.technologyChoices.flatMap((tech) => [tech.name, tech.description, tech.entitySubtypeCode, tech.entityTypeCode]),
+    ].map(normalizeForMatch).join(" ");
+    if (haystack.includes("next") || haystack.includes("next.js") || subtype.includes("web") || subtype.includes("portal") || subtype.includes("frontend")) {
+        return {
+            key: "next-web",
+            label: "Next.js web application",
+            runtime: "Node.js + Next.js",
+            devCommand: "npm run dev",
+            buildCommand: "npm run build",
+            entrySummary: "App Router web app with a simple landing page and architecture notes route.",
+            nextSteps: [
+                "Replace the placeholder app route with the real user journeys.",
+                "Connect the recommended services and data sources from the proposal.",
+                "Add policy control checks into CI before first release.",
+            ],
+        };
+    }
+    if (haystack.includes("react")) {
+        return {
+            key: "react-web",
+            label: "React front-end application",
+            runtime: "Node.js + React",
+            devCommand: "npm run dev",
+            buildCommand: "npm run build",
+            entrySummary: "React single-page app starter with proposal notes embedded in the UI.",
+            nextSteps: [
+                "Replace the placeholder components with the real application screens.",
+                "Wire in API/data integrations from the selected technology stack.",
+                "Add UI and accessibility tests before first handover.",
+            ],
+        };
+    }
+    if (haystack.includes("python") || haystack.includes("fastapi") || haystack.includes("django") || haystack.includes("flask")) {
+        return {
+            key: "python-api",
+            label: "Python API service",
+            runtime: "Python + FastAPI-style service",
+            devCommand: "python -m app.main",
+            buildCommand: "python -m compileall app",
+            entrySummary: "Python service scaffold with health endpoint and proposal docs.",
+            nextSteps: [
+                "Replace the placeholder endpoint with the application API surface.",
+                "Add dependency management and environment configuration for the target platform.",
+                "Implement the policy controls as startup checks, logging, and tests.",
+            ],
+        };
+    }
+    if (haystack.includes("worker") || haystack.includes("queue") || haystack.includes("job") || subtype.includes("service")) {
+        return {
+            key: "worker-service",
+            label: "Background worker service",
+            runtime: "Node.js worker/service",
+            devCommand: "npm run dev",
+            buildCommand: "npm run build",
+            entrySummary: "Worker starter with job processor placeholder and operational runbook notes.",
+            nextSteps: [
+                "Replace the sample processor with the real workload handler.",
+                "Connect queue, scheduler, or event infrastructure from the chosen stack.",
+                "Add observability and retry controls before production use.",
+            ],
+        };
+    }
+    if (haystack.includes("api") || haystack.includes("express") || haystack.includes("nest") || haystack.includes("service")) {
+        return {
+            key: "node-api",
+            label: "Node.js API service",
+            runtime: "Node.js + TypeScript API",
+            devCommand: "npm run dev",
+            buildCommand: "npm run build",
+            entrySummary: "TypeScript API starter with health route and proposal-backed service notes.",
+            nextSteps: [
+                "Replace the sample route with the real API contract.",
+                "Add persistence and integration adapters based on the selected technologies.",
+                "Implement automated tests and policy evidence capture in CI.",
+            ],
+        };
+    }
+    return {
+        key: "generic-ts",
+        label: "Generic TypeScript application",
+        runtime: "TypeScript starter",
+        devCommand: "npm run dev",
+        buildCommand: "npm run build",
+        entrySummary: "Lightweight TypeScript starter with proposal context and implementation placeholders.",
+        nextSteps: [
+            "Replace the starter files with the real application structure.",
+            "Bring in the frameworks and services recommended in the proposal.",
+            "Add delivery tests and policy evidence as implementation starts.",
+        ],
+    };
+}
+function buildReadme(proposal, template) {
+    const technologies = proposal.technologyChoices.map((item) => item.name);
+    const policies = proposal.policyControls.map((item) => item.name);
+    return `# ${proposal.application.name}
+
+${proposal.application.description ?? "Application scaffold generated from a NexArch proposal."}
+
+## Starter template
+
+- Template: ${template.label}
+- Runtime: ${template.runtime}
+- Suggested dev command: \`${template.devCommand}\`
+- Suggested build command: \`${template.buildCommand}\`
+- Starter shape: ${template.entrySummary}
+
+## Proposal summary
+
+- Workflow state: ${proposal.application.workflowState}
+- Application subtype: ${proposal.application.entitySubtypeCode ?? "Not specified"}
+- Recommendation basis: ${proposal.application.recommendationBasis ?? "Not specified"}
+- NexArch reference: ${proposal.application.entityRef ?? proposal.application.id}
+
+${proposal.application.recommendationSummary ? `## Recommendation notes\n\n${proposal.application.recommendationSummary}\n\n` : ""}## Suggested technology choices
+
+${formatBulletList(technologies)}
+
+## Policy controls to satisfy
+
+${formatBulletList(policies)}
+
+## Getting started
+
+${template.nextSteps.map((step, index) => `${index + 1}. ${step}`).join("\n")}
+`;
+}
+function buildProposalMarkdown(proposal) {
+    const techLines = proposal.technologyChoices.map((tech) => `${tech.name}${tech.entitySubtypeCode ? ` (${tech.entitySubtypeCode})` : ""}${tech.description ? ` — ${tech.description}` : ""}`);
+    const policyLines = proposal.policyControls.map((control) => `${control.name}${control.description ? ` — ${control.description}` : ""}`);
+    return `# NexArch proposal context\n\n## Application\n\n- Name: ${proposal.application.name}\n- ID: ${proposal.application.id}\n- Reference: ${proposal.application.entityRef ?? "n/a"}\n- Subtype: ${proposal.application.entitySubtypeCode ?? "n/a"}\n- Description: ${proposal.application.description ?? "n/a"}\n- Recommendation basis: ${proposal.application.recommendationBasis ?? "n/a"}\n- Proposal source: ${proposal.proposal.proposalSource ?? "n/a"}\n\n${proposal.application.recommendationSummary ? `## Recommendation summary\n\n${proposal.application.recommendationSummary}\n\n` : ""}## Technology choices\n\n${formatBulletList(techLines)}\n\n## Policy controls\n\n${formatBulletList(policyLines)}\n`;
+}
+function buildPolicyMarkdown(proposal) {
+    if (proposal.policyControls.length === 0) {
+        return "# Policy controls\n\nNo explicit policy controls were linked to this proposal.\n";
+    }
+    return `# Policy controls\n\n${proposal.policyControls.map((control) => {
+        const guidance = trimText(typeof control.controlAttributes.summary === "string" ? control.controlAttributes.summary : null);
+        const rules = Array.isArray(control.controlAttributes.rules)
+            ? control.controlAttributes.rules
+                .map((rule) => trimText(typeof rule.title === "string" ? rule.title : typeof rule.code === "string" ? rule.code : null))
+                .filter((value) => Boolean(value))
+            : [];
+        return `## ${control.name}\n\n${control.description ?? "No description provided."}\n\n${guidance ? `Guidance: ${guidance}\n\n` : ""}${rules.length > 0 ? `Rules\n\n${formatBulletList(rules)}\n` : ""}`;
+    }).join("\n")}`;
+}
+function buildTsConfig() {
+    return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}
+`;
+}
+function buildPackageJson(proposal, template) {
+    const base = {
+        name: slugify(proposal.application.name),
+        version: "0.1.0",
+        private: true,
+        description: proposal.application.description ?? `Scaffold for ${proposal.application.name}`,
+    };
+    if (template.key === "next-web") {
+        return `${safeJson({
+            ...base,
+            scripts: { dev: "next dev", build: "next build", start: "next start", lint: "next lint" },
+            dependencies: { next: "latest", react: "latest", "react-dom": "latest" },
+        })}\n`;
+    }
+    if (template.key === "react-web") {
+        return `${safeJson({
+            ...base,
+            scripts: { dev: "vite", build: "vite build", preview: "vite preview" },
+            dependencies: { react: "latest", "react-dom": "latest" },
+            devDependencies: { typescript: "latest", vite: "latest" },
+        })}\n`;
+    }
+    if (template.key === "python-api") {
+        return `${safeJson({
+            ...base,
+            note: "Python scaffold - see pyproject.toml for runtime dependencies.",
+        })}\n`;
+    }
+    return `${safeJson({
+        ...base,
+        type: "module",
+        scripts: { dev: "node --watch src/index.ts", build: "tsc --noEmit false", start: "node dist/index.js" },
+        devDependencies: { typescript: "latest", "@types/node": "latest" },
+    })}\n`;
+}
+function buildStarterSource(proposal, template) {
+    const suffix = proposal.application.name.replace(/[^a-zA-Z0-9]+/g, "") || "Application";
+    switch (template.key) {
+        case "next-web":
+            return [
+                {
+                    relativePath: "src/app/page.tsx",
+                    content: `export default function Home() {
+  return (
+    <main style={{ padding: 32, fontFamily: "Arial, sans-serif" }}>
+      <h1>${proposal.application.name}</h1>
+      <p>${proposal.application.description ?? "Application scaffold generated from a NexArch proposal."}</p>
+      <p>Start here by replacing this page with the real user journey.</p>
+    </main>
+  );
+}
+`,
+                },
+                {
+                    relativePath: "src/app/layout.tsx",
+                    content: `export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+`,
+                },
+            ];
+        case "react-web":
+            return [
+                {
+                    relativePath: "src/main.tsx",
+                    content: `import React from "react";
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+`,
+                },
+                {
+                    relativePath: "src/App.tsx",
+                    content: `export function App() {
+  return (
+    <main style={{ padding: 32, fontFamily: "Arial, sans-serif" }}>
+      <h1>${proposal.application.name}</h1>
+      <p>${proposal.application.description ?? "Application scaffold generated from a NexArch proposal."}</p>
+    </main>
+  );
+}
+`,
+                },
+                {
+                    relativePath: "index.html",
+                    content: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${proposal.application.name}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`,
+                },
+            ];
+        case "python-api":
+            return [
+                {
+                    relativePath: "app/main.py",
+                    content: `def healthcheck() -> dict[str, str]:
+    return {"status": "ok", "application": ${JSON.stringify(proposal.application.name)}}
+
+
+if __name__ == "__main__":
+    print(healthcheck())
+`,
+                },
+                {
+                    relativePath: "pyproject.toml",
+                    content: `[project]
+name = "${slugify(proposal.application.name)}"
+version = "0.1.0"
+description = ${JSON.stringify(proposal.application.description ?? `Scaffold for ${proposal.application.name}`)}
+requires-python = ">=3.11"
+dependencies = []
+`,
+                },
+            ];
+        case "worker-service":
+            return [
+                {
+                    relativePath: "src/index.ts",
+                    content: `export async function start${suffix}Worker(): Promise<void> {
+  console.log(${JSON.stringify(`Worker scaffold ready for ${proposal.application.name}`)});
+}
+
+start${suffix}Worker().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+`,
+                },
+                {
+                    relativePath: "src/jobs/example-job.ts",
+                    content: `export async function processExampleJob(): Promise<void> {
+  console.log("Replace this with the real job handler.");
+}
+`,
+                },
+            ];
+        case "node-api":
+            return [
+                {
+                    relativePath: "src/index.ts",
+                    content: `import { createServer } from "node:http";
+
+const server = createServer((_req, res) => {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({ status: "ok", application: ${JSON.stringify(proposal.application.name)} }));
+});
+
+server.listen(3000, () => {
+  console.log("API starter listening on http://localhost:3000");
+});
+`,
+                },
+            ];
+        default:
+            return [
+                {
+                    relativePath: "src/index.ts",
+                    content: `export function start${suffix}App(): void {
+  console.log(${JSON.stringify(`Start building ${proposal.application.name}`)});
+}
+`,
+                },
+            ];
+    }
+}
+function buildTemplateFiles(proposal, template) {
+    const shared = [
+        { relativePath: ".gitignore", content: "node_modules/\ndist/\n.env\n.DS_Store\n.venv/\n" },
+        { relativePath: ".editorconfig", content: "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\nindent_style = space\nindent_size = 2\n" },
+        { relativePath: "README.md", content: buildReadme(proposal, template) },
+        { relativePath: "docs/architecture/nexarch-proposal.md", content: buildProposalMarkdown(proposal) },
+        { relativePath: "docs/architecture/policy-controls.md", content: buildPolicyMarkdown(proposal) },
+        { relativePath: ".nexarch/proposal.json", content: `${safeJson({ ...proposal, scaffoldTemplate: template })}\n` },
+        { relativePath: "tests/README.md", content: "Add delivery tests for the new application here.\n" },
+        { relativePath: ".env.example", content: "# Add environment variables for this application here\n" },
+    ];
+    shared.push({ relativePath: "package.json", content: buildPackageJson(proposal, template) });
+    if (["node-api", "worker-service", "generic-ts"].includes(template.key)) {
+        shared.push({ relativePath: "tsconfig.json", content: buildTsConfig() });
+    }
+    return [...shared, ...buildStarterSource(proposal, template)];
+}
+function scaffoldProposal(targetDir, proposal) {
+    const template = inferStackTemplate(proposal);
+    const files = buildTemplateFiles(proposal, template);
+    for (const file of files) {
+        const outputPath = join(targetDir, file.relativePath);
+        ensureDir(dirname(outputPath));
+        writeFileSync(outputPath, file.content, "utf8");
+    }
+    return {
+        createdFiles: files.map((file) => join(targetDir, file.relativePath)),
+        template,
+    };
+}
+export async function proposalsStart(args) {
+    const asJson = parseFlag(args, "--json");
+    const nonInteractive = parseFlag(args, "--non-interactive");
+    const force = parseFlag(args, "--force");
+    const skipActivate = parseFlag(args, "--skip-activate");
+    const activateFlag = parseFlag(args, "--activate");
+    const applicationId = parseOptionValue(args, "--id") ?? parseOptionValue(args, "--application-id");
+    const targetDirArg = parseOptionValue(args, "--dir");
+    const reason = parseOptionValue(args, "--reason") ?? "Application scaffold started from approved proposal workflow";
+    const repoUrl = parseOptionValue(args, "--repo");
+    const creds = requireCredentials();
+    const listRaw = await callMcpTool("nexarch_list_proposed_applications", { companyId: creds.companyId }, { companyId: creds.companyId });
+    const list = parseToolText(listRaw);
+    const proposals = list.proposals ?? [];
+    if (proposals.length === 0) {
+        const payload = { ok: true, proposals: [], message: "No proposed applications found." };
+        if (asJson)
+            process.stdout.write(`${JSON.stringify(payload)}\n`);
+        else
+            console.log(payload.message);
+        return;
+    }
+    let chosen = applicationId
+        ? proposals.find((proposal) => proposal.id === applicationId)
+        : undefined;
+    if (!chosen && applicationId) {
+        throw new Error(`Proposal not found: ${applicationId}`);
+    }
+    if (!chosen) {
+        if (nonInteractive || !process.stdin.isTTY || !process.stdout.isTTY) {
+            if (proposals.length === 1) {
+                chosen = proposals[0];
+            }
+            else {
+                throw new Error("Multiple proposed applications found. Re-run with --id <applicationId>.");
+            }
+        }
+        else {
+            chosen = await promptChoice(proposals);
+        }
+    }
+    const getRaw = await callMcpTool("nexarch_get_proposed_application", { applicationId: chosen.id, companyId: creds.companyId }, { companyId: creds.companyId });
+    const getResult = parseToolText(getRaw);
+    const proposal = getResult.proposal;
+    if (!proposal)
+        throw new Error("Proposal context was not returned by MCP gateway.");
+    const suggestedDir = resolvePath(targetDirArg ?? slugify(proposal.application.name));
+    const targetDir = nonInteractive || targetDirArg
+        ? suggestedDir
+        : resolvePath(await promptValue(`Target directory [${suggestedDir}]: `, suggestedDir));
+    if (existsSync(targetDir) && !isDirectoryPath(targetDir)) {
+        throw new Error(`Target path is not a directory: ${targetDir}`);
+    }
+    if (existsSync(targetDir) && !isDirectoryEmpty(targetDir) && !force) {
+        throw new Error(`Target directory is not empty: ${targetDir}. Re-run with --force to allow writing into it.`);
+    }
+    const scaffold = scaffoldProposal(targetDir, proposal);
+    let activated = null;
+    const shouldActivate = skipActivate
+        ? false
+        : activateFlag || nonInteractive || !process.stdin.isTTY || !process.stdout.isTTY
+            ? true
+            : await confirm("Activate this proposal in NexArch now? [Y/n]: ", true);
+    if (shouldActivate) {
+        const activateRaw = await callMcpTool("nexarch_activate_proposed_application", {
+            applicationId: proposal.application.id,
+            companyId: creds.companyId,
+            reason,
+            scaffold: {
+                command: "nexarch proposals start",
+                template: scaffold.template,
+                targetDir,
+                repoUrl: trimText(repoUrl),
+                createdAt: new Date().toISOString(),
+                createdFiles: scaffold.createdFiles,
+            },
+            agentContext: {
+                initiatedBy: "nexarch-cli",
+                command: "proposals start",
+                operatorEmail: creds.email,
+            },
+        }, { companyId: creds.companyId });
+        activated = parseToolText(activateRaw);
+    }
+    const payload = {
+        ok: true,
+        proposalId: proposal.application.id,
+        proposalName: proposal.application.name,
+        targetDir,
+        activated,
+        scaffold,
+    };
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(payload)}\n`);
+        return;
+    }
+    console.log(`\nStarted ${proposal.application.name}`);
+    console.log(`- Proposal: ${proposal.application.id}`);
+    console.log(`- Folder  : ${targetDir}`);
+    console.log(`- Template: ${scaffold.template.label}`);
+    console.log(`- Runtime : ${scaffold.template.runtime}`);
+    console.log(`- Files   : ${scaffold.createdFiles.length} created`);
+    console.log(`- State   : ${activated ? `${activated.status}${activated.alreadyActive ? " (already active)" : ""}` : "left in proposed state"}`);
+    console.log("\nNext steps:");
+    scaffold.template.nextSteps.forEach((step, index) => console.log(`${index + 1}. ${step}`));
+    console.log(`${scaffold.template.nextSteps.length + 1}. Use docs/architecture/nexarch-proposal.md and policy-controls.md while building.`);
+    console.log(`${scaffold.template.nextSteps.length + 2}. Check the delivery back into NexArch when implementation is underway.`);
+}

package/dist/index.js

@@ -24,6 +24,7 @@ import { policyAuditSubmit } from "./commands/policy-audit-submit.js";
 import { policyAuditResults } from "./commands/policy-audit-results.js";
 import { appliedPolicies } from "./commands/applied-policies.js";
 import { governanceSummary } from "./commands/governance-summary.js";
+import { proposalsStart } from "./commands/proposals-start.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -61,6 +62,13 @@ async function main() {
             return;
         }
     }
+    if (command === "proposals") {
+        const [subcommand, ...subArgs] = args;
+        if (subcommand === "start") {
+            await proposalsStart(subArgs);
+            return;
+        }
+    }
     const handler = commands[command ?? ""];
     if (!handler) {
         console.log(`
@@ -172,9 +180,24 @@ Usage:
                                --to <toExternalKey>
                                --limit <1-500>
                                --json
-  nexarch check-in    Preview pending application-target commands (no auto-claim).
+  nexarch check-in    Preview pending application-target commands (no auto-claim)
+                      and report any applications currently in draft state so the
+                      agent can prompt the user to explore and instantiate them.
                       Scope is resolved server-side from active company context.
                       Options: --agent-key <key>   override stored agent key
+                               --json              JSON output includes draftApplications[]
+  nexarch proposals start
+                      Start a new application workspace from a proposed NexArch app.
+                      Lists proposed apps, lets you choose one, writes a starter
+                      project scaffold, and activates the proposal to active.
+                      Options: --id <applicationId>
+                               --dir <path>
+                               --reason <text>
+                               --repo <url>
+                               --skip-activate
+                               --activate
+                               --force
+                               --non-interactive
                                --json
   nexarch command-claim
                       Explicitly claim a pending command by ID.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",