nexarch 0.12.4 → 0.12.6

package/dist/commands/init-project.js

@@ -1,5 +1,4 @@
 import process from "process";
-import * as readline from "node:readline/promises";
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, join, relative, resolve as resolvePath } from "node:path";
@@ -1069,43 +1068,6 @@ export function scoreApplicationCandidate(app, projectName, repoUrl) {
         return null;
     return { entityRef, name: app.name, score: Math.min(1, score), reasons };
 }
-async function promptApplicationChoice(matches, allApps, suggested) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    try {
-        console.log("\nExisting application entities found.");
-        if (suggested) {
-            console.log(`Suggested match: ${suggested.name} (${suggested.entityRef}) score=${suggested.score.toFixed(2)} [${suggested.reasons.join(", ")}]`);
-        }
-        console.log("\nChoose target application:");
-        const options = [];
-        let index = 1;
-        for (const m of matches.slice(0, 5)) {
-            options.push({
-                key: String(index++),
-                label: `${m.name} (${m.entityRef}) score=${m.score.toFixed(2)}`,
-                value: m.entityRef,
-            });
-        }
-        options.push({ key: String(index++), label: "Show all applications", value: "__show_all__" });
-        options.push({ key: String(index), label: "Create a new application", value: "__create__" });
-        for (const o of options)
-            console.log(`  ${o.key}) ${o.label}`);
-        const answer = (await rl.question("Select option: ")).trim();
-        const chosen = options.find((o) => o.key === answer)?.value;
-        if (chosen === "__show_all__") {
-            console.log("\nAll applications:");
-            allApps.forEach((a, i) => console.log(`  ${i + 1}) ${a.name} (${a.entityRef ?? a.externalKey ?? "n/a"})`));
-            const pick = Number((await rl.question("Pick application number or 0 to create new: ")).trim());
-            if (!Number.isFinite(pick) || pick <= 0 || pick > allApps.length)
-                return "__create__";
-            return allApps[pick - 1].entityRef ?? allApps[pick - 1].externalKey ?? "__create__";
-        }
-        return chosen && chosen !== "__show_all__" ? chosen : "__create__";
-    }
-    finally {
-        rl.close();
-    }
-}
 // ─── Main command ─────────────────────────────────────────────────────────────
 export async function initProject(args) {
     const asJson = parseFlag(args, "--json");
@@ -1162,20 +1124,32 @@ export async function initProject(args) {
     const displayName = nameOverride ?? projectName;
     const projectSlug = slugify(displayName);
     let projectExternalKey = `${entityTypeOverride}:${projectSlug}`;
+    // ADR 8a (docs/strategy/adr-ontology-reset-v1.md): the repository is modelled
+    // as a `project` entity — evidence, not architecture. Monorepos no longer get
+    // a synthetic root application; deployable packages become applications
+    // sourced_from the project. projectExternalKey remains the APPLICATION key,
+    // used only when the repo is itself a single deployable.
+    const projectConstruct = entityTypeOverride === "application";
+    const isMonorepo = subPackages.length > 0;
+    const projectDirName = nameOverride ?? basename(dir);
+    const projectDirSlug = slugify(projectDirName);
+    const projectEntityKey = `project:${projectDirSlug}`;
     // Compute sub-package external keys now that projectSlug is known.
     // Unscoped names (no "/") get prefixed with the project slug to avoid ambiguous keys
     // like "application:crawler" — they become "application:whatsontap-crawler" instead,
     // matching what the enrichment agent would naturally choose.
+    // Keys derive from the directory basename, not package.json name: paths are
+    // stable, unique within a repo, and human-meaningful, while npm names can
+    // collide with the project itself (this repo's CLI package is literally named
+    // "nexarch"). For existing layouts this reproduces the pre-8a keys
+    // byte-for-byte (application:nexarch_web), keeping re-runs idempotent.
+    const seenSubSlugs = new Set();
     for (const sp of subPackages) {
-        const nameSlug = slugify(sp.name);
-        const needsPrefix = !sp.name.includes("/") && !nameSlug.startsWith(projectSlug);
-        let keySlug = needsPrefix ? `${projectSlug}_${nameSlug}` : nameSlug;
-        // Avoid key collision with the top-level project (e.g. sub-package named "nexarch").
-        if (`${sp.entityType}:${keySlug}` === projectExternalKey) {
-            const relSlug = slugify(sp.relativePath.replace(/\//g, "_"));
-            keySlug = relSlug ? `${projectSlug}_${relSlug}` : `${projectSlug}_${nameSlug}_sub`;
-        }
-        sp.externalKey = `${sp.entityType}:${keySlug}`;
+        let dirSlug = slugify(basename(sp.relativePath));
+        if (seenSubSlugs.has(dirSlug))
+            dirSlug = slugify(sp.relativePath.replace(/\//g, "_"));
+        seenSubSlugs.add(dirSlug);
+        sp.externalKey = `${sp.entityType}:${projectDirSlug}_${dirSlug}`;
     }
     if (!asJson) {
         console.log(`  Project : ${displayName} (${entityTypeOverride})`);
@@ -1214,9 +1188,10 @@ export async function initProject(args) {
         const output = {
             dryRun: true,
             project: {
-                name: displayName,
-                externalKey: projectExternalKey,
-                entityType: entityTypeOverride,
+                name: projectConstruct ? projectDirName : displayName,
+                externalKey: projectConstruct ? projectEntityKey : projectExternalKey,
+                entityType: projectConstruct ? "project" : entityTypeOverride,
+                ...(projectConstruct ? { subtype: isMonorepo ? "project_monorepo" : "project_repository" } : {}),
                 sourceRepository: detectedRepo
                     ? {
                         ref: detectedRepo.rawRef,
@@ -1270,13 +1245,37 @@ export async function initProject(args) {
     const repoUrl = repoUrlOverride ?? detectedRepo?.url ?? null;
     const sourceVcsType = detectedRepo?.vcsType ?? "unknown";
     const sourceProvider = detectedRepo?.provider ?? "unknown";
-    if (entityTypeOverride === "application" && !forceCreateApplication) {
+    if (projectConstruct && isMonorepo && (applicationRefOverride || forceCreateApplication) && !asJson) {
+        console.log("\nNote: monorepo detected — no root application is created (ADR 8a); --application-ref/--create-application apply only to single-package repositories.");
+    }
+    if (entityTypeOverride === "application" && !forceCreateApplication && !isMonorepo) {
         if (applicationRefOverride) {
             projectExternalKey = applicationRefOverride;
             if (!asJson)
                 console.log(`\nUsing --application-ref target: ${projectExternalKey}`);
         }
         else {
+            // Seed S2 auto-map: when a reviewer previously declined a proposal with
+            // this name as a duplicate, a company alias maps it to the surviving
+            // application. Resolving the name first means the human's "no" is
+            // honoured automatically — the scan maps instead of re-proposing.
+            try {
+                const aliasRaw = await callMcpProfiled("nexarch_resolve_reference", { names: [displayName], companyId: creds.companyId }, { batchSize: 1 });
+                const aliasData = parseToolText(aliasRaw);
+                const aliasHit = (aliasData.results ?? []).find((r) => r.resolved && r.entityTypeCode === "application" && r.canonicalExternalRef?.startsWith("application:"));
+                if (aliasHit?.canonicalExternalRef) {
+                    projectExternalKey = aliasHit.canonicalExternalRef;
+                    if (!asJson) {
+                        console.log(`\nAuto-mapped via workspace alias: "${displayName}" → ${projectExternalKey} (${aliasHit.canonicalName ?? "existing application"})`);
+                        console.log("  A reviewer previously mapped this name to an existing application. To create a separate application anyway, re-run with --create-application.");
+                    }
+                }
+            }
+            catch {
+                // Alias resolution is best-effort; fall through to candidate scoring.
+            }
+        }
+        if (!applicationRefOverride && projectExternalKey === `${entityTypeOverride}:${projectSlug}`) {
             const appsRaw = await callMcpProfiled("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: creds.companyId }, { entityTypeCode: "application", limit: 500 });
             const appsData = parseToolText(appsRaw);
             const apps = (appsData.entities ?? []).filter((e) => (e.entityRef ?? e.externalKey));
@@ -1287,63 +1286,30 @@ export async function initProject(args) {
                     .sort((a, b) => b.score - a.score);
                 const suggested = matches.length > 0 ? matches[0] : null;
                 const highConfidence = suggested && suggested.score >= 0.85;
-                const interactiveAllowed = !nonInteractive && process.stdin.isTTY;
+                // ADR 8d: the interactive "Choose target application" prompt is gone.
+                // It demanded an architectural judgement from whoever happened to run
+                // the command, in a terminal, sixty seconds into using the product —
+                // and blocked non-interactive runs entirely. The default is now to
+                // create a new application, which arrives as PROPOSED (8b): the
+                // mapping judgement moves to the activation card, where similarity
+                // evidence renders for the human reviewing it (8c). Explicit mapping
+                // remains available via --application-ref and --auto-map-application.
                 if (autoMapApplication && highConfidence) {
                     projectExternalKey = suggested.entityRef;
                     if (!asJson)
                         console.log(`\nAuto-mapped to existing application: ${suggested.name} (${projectExternalKey})`);
                 }
-                else if (!interactiveAllowed) {
-                    const message = "Application mapping requires explicit choice in non-interactive mode. Pass --application-ref <entityRef> or --create-application (or run interactively).";
-                    const existingApplications = apps.slice(0, 25).map((a) => ({
-                        entityRef: a.entityRef ?? a.externalKey,
-                        name: a.name,
-                        entityTypeCode: a.entityTypeCode,
-                    }));
-                    if (asJson) {
-                        process.stdout.write(`${JSON.stringify({
-                            ok: true,
-                            status: "input_required",
-                            code: "APPLICATION_MAPPING_REQUIRED",
-                            message,
-                            suggested: suggested ?? null,
-                            candidates: matches.slice(0, 10),
-                            existingApplications,
-                            requiredInput: {
-                                applicationRefOption: "--application-ref <entityRef>",
-                                createOption: "--create-application",
-                            },
-                        }, null, 2)}\n`);
-                        return;
-                    }
-                    console.log("\nInput required before continuing:");
-                    console.log(`  ${message}`);
-                    if (suggested) {
-                        console.log(`  Suggested: ${suggested.name} (${suggested.entityRef}) score=${suggested.score.toFixed(2)}`);
-                    }
-                    if (existingApplications.length > 0) {
-                        console.log("  Existing applications:");
-                        for (const app of existingApplications) {
-                            console.log(`    - ${app.name} (${app.entityRef})`);
-                        }
-                    }
-                    return;
-                }
-                else {
-                    const chosen = await promptApplicationChoice(matches, apps, highConfidence ? suggested : null);
-                    if (chosen !== "__create__") {
-                        projectExternalKey = chosen;
-                        if (!asJson)
-                            console.log(`Mapped to existing application: ${projectExternalKey}`);
-                    }
-                    else if (!asJson) {
-                        console.log("Creating a new application entity for this project.");
+                else if (matches.length > 0 && !asJson) {
+                    console.log("\nSimilar existing applications found (registering a new proposed application anyway — the reviewer sees these again at activation):");
+                    for (const m of matches.slice(0, 5)) {
+                        console.log(`  - ${m.name} (${m.entityRef}) score=${m.score.toFixed(2)} [${m.reasons.join(", ")}]`);
                     }
+                    console.log("  To map to one instead, re-run with: --application-ref <entityRef>");
                 }
             }
         }
     }
-    logProgress("application.target", projectExternalKey);
+    logProgress(projectConstruct ? "project.target" : "application.target", projectConstruct ? (isMonorepo ? projectEntityKey : `${projectEntityKey} + ${projectExternalKey}`) : projectExternalKey);
     // In refresh mode, snapshot the current graph state for this project before writing,
     // so we can diff what changed and surface stale relationships to the agent.
     let currentOutgoingRels = [];
@@ -1376,26 +1342,46 @@ export async function initProject(args) {
         : undefined;
     // Build entity list — project entity + all resolved reference entities
     const entities = [];
-    // The project itself — default subtype app_custom_built for application type
-    const projectSubtype = entityTypeOverride === "application" ? "app_custom_built" : undefined;
-    entities.push({
-        externalKey: projectExternalKey,
-        entityTypeCode: entityTypeOverride,
-        ...(projectSubtype ? { entitySubtypeCode: projectSubtype } : {}),
-        name: displayName,
-        confidence: 1,
-        attributes: {
-            source_dir: dir,
-            scanned_at: nowIso,
-            package_json_count: packageJsonCount,
-            ...(repoUrl ? { repository_url: repoUrl, source_repository_url: repoUrl } : {}),
-            repository_ref: repoRef,
-            source_repository_ref: repoRef,
-            source_vcs_type: sourceVcsType,
-            source_provider: sourceProvider,
-            ...(detectedRepo?.canonicalRepoRef ? { source_repository_component_ref: detectedRepo.canonicalRepoRef } : {}),
-        },
-    });
+    const scanProvenanceAttributes = {
+        source_dir: dir,
+        scanned_at: nowIso,
+        package_json_count: packageJsonCount,
+        ...(repoUrl ? { repository_url: repoUrl, source_repository_url: repoUrl } : {}),
+        repository_ref: repoRef,
+        source_repository_ref: repoRef,
+        source_vcs_type: sourceVcsType,
+        source_provider: sourceProvider,
+        ...(detectedRepo?.canonicalRepoRef ? { source_repository_component_ref: detectedRepo.canonicalRepoRef } : {}),
+    };
+    // The repository as evidence: a `project` entity (ADR 8a). It arrives active —
+    // a repository is a fact needing no review — while the applications it sources
+    // arrive proposed (ADR 8b, enforced at the gateway).
+    if (projectConstruct) {
+        entities.push({
+            externalKey: projectEntityKey,
+            entityTypeCode: "project",
+            entitySubtypeCode: isMonorepo ? "project_monorepo" : "project_repository",
+            name: projectDirName,
+            confidence: 1,
+            attributes: {
+                ...scanProvenanceAttributes,
+                ...(projectName !== projectDirName ? { npm_package_name: projectName } : {}),
+            },
+        });
+    }
+    // The root application exists only when the repo IS a single deployable
+    // (or in legacy non-application mode). A monorepo's container is the project.
+    if (!projectConstruct || !isMonorepo) {
+        const projectSubtype = entityTypeOverride === "application" ? "app_custom_built" : undefined;
+        entities.push({
+            externalKey: projectExternalKey,
+            entityTypeCode: entityTypeOverride,
+            ...(projectSubtype ? { entitySubtypeCode: projectSubtype } : {}),
+            name: displayName,
+            confidence: 1,
+            attributes: scanProvenanceAttributes,
+        });
+    }
     // Resolved reference entities (deduplicated by canonical external ref)
     const seenRefs = new Set();
     for (const r of resolvedItems) {
@@ -1412,7 +1398,9 @@ export async function initProject(args) {
         });
     }
     // Ensure source repository component is represented when we can infer one.
-    if (detectedRepo?.canonicalRepoRef && !seenRefs.has(detectedRepo.canonicalRepoRef)) {
+    // Under the project construct the project entity IS the repository, so the
+    // separate technology_component stand-in is no longer created.
+    if (!projectConstruct && detectedRepo?.canonicalRepoRef && !seenRefs.has(detectedRepo.canonicalRepoRef)) {
         seenRefs.add(detectedRepo.canonicalRepoRef);
         entities.push({
             externalKey: detectedRepo.canonicalRepoRef,
@@ -1439,13 +1427,18 @@ export async function initProject(args) {
         if (seenSubKeys.has(sp.externalKey))
             continue;
         seenSubKeys.add(sp.externalKey);
+        const dirDisplayName = basename(sp.relativePath);
         entities.push({
             externalKey: sp.externalKey,
             entityTypeCode: sp.entityType,
             entitySubtypeCode: sp.subtype,
-            name: sp.name,
+            name: dirDisplayName,
             confidence: 0.8,
-            attributes: { source_dir: `${dir}/${sp.relativePath}`, scanned_at: nowIso },
+            attributes: {
+                source_dir: `${dir}/${sp.relativePath}`,
+                scanned_at: nowIso,
+                ...(sp.name && sp.name !== dirDisplayName ? { npm_package_name: sp.name } : {}),
+            },
         });
     }
     // Build a lookup from input name to resolved result for enrichment task and sub-app wiring
@@ -1487,8 +1480,13 @@ export async function initProject(args) {
         seenRelPairs.add(key);
         relationships.push({ relationshipTypeCode: type, fromEntityExternalKey: from, toEntityExternalKey: to, confidence, attributes });
     }
-    // Root-level deps → top-level project
-    for (const r of resolvedItems) {
+    // Root-level deps → the root application (single-package/legacy only). A
+    // project carries provenance, not dependencies — the ontology forbids
+    // depends_on FROM project by design.
+    if (projectConstruct && isMonorepo && rootDepNames.size > 0 && !asJson) {
+        console.log(`  Note: ${rootDepNames.size} root-level manifest dep(s) recorded as entities; not wired to the project (shared tooling).`);
+    }
+    for (const r of (projectConstruct && isMonorepo ? [] : resolvedItems)) {
         if (!r.canonicalExternalRef || !r.entityTypeCode)
             continue;
         if (!rootDepNames.has(r.input) && !rootDepNames.has(r.normalised))
@@ -1505,11 +1503,16 @@ export async function initProject(args) {
         if (!sp.externalKey || seenSubKeys.has(`rel:${sp.externalKey}`))
             continue;
         seenSubKeys.add(`rel:${sp.externalKey}`);
-        // Wire structural relationship to the top-level project entity:
-        // - application_component → part_of → root (component within a single deployable app)
-        // - application → root composes sub-app (ontology only allows application on part_of FROM
-        //   for application_component/application_function, not application itself)
-        if (sp.entityType === "application_component") {
+        // ADR 8a: provenance, not containment. Every application-like package is
+        // sourced_from the project; the composes/part_of wiring to a synthetic root
+        // is gone. Genuine product composition is a human assertion made through
+        // the proposal flow, never inferred from directory layout.
+        if (projectConstruct) {
+            if (isApplicationLikeEntityType(sp.entityType)) {
+                addRel("sourced_from", sp.externalKey, projectEntityKey, 1);
+            }
+        }
+        else if (sp.entityType === "application_component") {
             addRel("part_of", sp.externalKey, projectExternalKey);
         }
         else if (sp.entityType === "application") {
@@ -1550,15 +1553,21 @@ export async function initProject(args) {
     catch {
         // keep fallback
     }
-    addRel("accountable_for", orgExternalKey, projectExternalKey, 1);
+    if (!projectConstruct || !isMonorepo) {
+        addRel("accountable_for", orgExternalKey, projectExternalKey, 1);
+    }
     // Also accountable_for any sub-package applications
     for (const sp of subPackages) {
         if (sp.externalKey && isApplicationLikeEntityType(sp.entityType)) {
             addRel("accountable_for", orgExternalKey, sp.externalKey, 1);
         }
     }
-    // Project depends_on its source repository component when resolved/inferred.
-    if (detectedRepo?.canonicalRepoRef) {
+    // Single-package repos: the one application is sourced_from the project.
+    if (projectConstruct && !isMonorepo) {
+        addRel("sourced_from", projectExternalKey, projectEntityKey, 1);
+    }
+    // Legacy only: the project entity now carries repository provenance itself.
+    if (!projectConstruct && detectedRepo?.canonicalRepoRef) {
         addRel("depends_on", projectExternalKey, detectedRepo.canonicalRepoRef, 0.95);
     }
     // In refresh mode the raw graph state (fetched above) is emitted alongside scan results
@@ -1650,29 +1659,50 @@ export async function initProject(args) {
         // so agents using --json receive the same mandatory instructions as text-mode agents.
         const pendingSteps = [];
         let stepNum = 1;
-        pendingSteps.push({
-            step: stepNum++,
-            action: "enrich_entity",
-            instruction: `Enrich the project entity with a meaningful name, description, subtype, and icon.`,
-            command: `nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`,
-            ...(entityTypeOverride === "application"
-                ? { notes: [APPLICATION_SUBTYPE_HINT, "Choose app_custom_built as the default if none of the others clearly apply."] }
-                : {}),
-        });
+        if (projectConstruct) {
+            pendingSteps.push({
+                step: stepNum++,
+                action: "describe_project",
+                instruction: `Give the project (repository) entity a short description of what lives in this repo.`,
+                command: `nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "${projectDirName}" --description "..."`,
+            });
+        }
+        if (!projectConstruct || !isMonorepo) {
+            pendingSteps.push({
+                step: stepNum++,
+                action: "enrich_entity",
+                instruction: `Enrich the application entity with a meaningful name, description, subtype, and icon.`,
+                command: `nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`,
+                ...(entityTypeOverride === "application"
+                    ? { notes: [APPLICATION_SUBTYPE_HINT, "Choose app_custom_built as the default if none of the others clearly apply."] }
+                    : {}),
+            });
+        }
         if (subPackages.length > 0) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "classify_sub_packages",
-                instruction: `For each sub-package in classifyPackages: (1) run update-entity to confirm type/subtype/name/description, then (2) immediately run add-relationship to wire the structural relationship. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo). Always run update-entity before add-relationship for each package.`,
-                commandTemplates: {
-                    updateEntity: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
-                    wireRelationship: `nexarch add-relationship --from "<from>" --to "<to>" --type <composes|part_of>  (see structuralRelationship on each classifyPackages entry)`,
-                },
-                notes: [
-                    "application sub-packages: parent composes sub-app  →  add-relationship --from parent --to sub-app --type composes",
-                    "application_component sub-packages: component part_of parent  →  add-relationship --from sub-pkg --to parent --type part_of",
-                    "Do NOT wire the relationship before the entity exists at the correct key.",
-                ],
+                instruction: projectConstruct
+                    ? `For each sub-package in classifyPackages, run update-entity to confirm type/subtype/name/description. The sourced_from relationship to the project is wired automatically — no structural add-relationship is needed. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo) and the old key's sourced_from should be retired.`
+                    : `For each sub-package in classifyPackages: (1) run update-entity to confirm type/subtype/name/description, then (2) immediately run add-relationship to wire the structural relationship. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo). Always run update-entity before add-relationship for each package.`,
+                commandTemplates: projectConstruct
+                    ? {
+                        updateEntity: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
+                    }
+                    : {
+                        updateEntity: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
+                        wireRelationship: `nexarch add-relationship --from "<from>" --to "<to>" --type <composes|part_of>  (see structuralRelationship on each classifyPackages entry)`,
+                    },
+                notes: projectConstruct
+                    ? [
+                        `Every package is already sourced_from ${projectEntityKey} — provenance is automatic.`,
+                        "New applications arrive as proposed and wait for human activation in the workspace — do not describe them as fully registered.",
+                    ]
+                    : [
+                        "application sub-packages: parent composes sub-app  →  add-relationship --from parent --to sub-app --type composes",
+                        "application_component sub-packages: component part_of parent  →  add-relationship --from sub-pkg --to parent --type part_of",
+                        "Do NOT wire the relationship before the entity exists at the correct key.",
+                    ],
             });
         }
         if (entityTypeOverride === "application") {
@@ -1682,7 +1712,7 @@ export async function initProject(args) {
                 instruction: `Review the codebase to identify discrete application functions (what the application does). Examine named modules, route layout, service boundaries, and any architecture documentation. Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). Only register functions clearly evidenced by the codebase — do not invent them.`,
                 commandTemplates: {
                     updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
-                    addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to "${projectExternalKey}" --type part_of`,
+                    addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to ${projectConstruct && isMonorepo ? '"<owning application key from classifyPackages>"' : `"${projectExternalKey}"`} --type part_of`,
                 },
             });
         }
@@ -1693,7 +1723,7 @@ export async function initProject(args) {
             commandTemplates: {
                 resolve: `nexarch resolve-names --names "..." --json`,
                 updateEntity: `nexarch update-entity --key "<canonicalExternalRef>" --entity-type "<entityType>" --name "..."`,
-                addRelationship: `nexarch add-relationship --from "${projectExternalKey}" --to "<canonicalExternalRef>" --type depends_on`,
+                addRelationship: `nexarch add-relationship --from ${projectConstruct && isMonorepo ? '"<the application that uses it>"' : `"${projectExternalKey}"`} --to "<canonicalExternalRef>" --type depends_on`,
             },
         });
         pendingSteps.push({
@@ -1702,7 +1732,7 @@ export async function initProject(args) {
             instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register each as a decision_record entity.`,
             commandTemplates: {
                 updateEntity: `nexarch update-entity --key "decision_record:${projectSlug}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`,
-                addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to "${projectExternalKey}" --type decides`,
+                addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`,
             },
         });
         const preservedEntities = entitiesResult.preserved ?? [];
@@ -1725,10 +1755,17 @@ export async function initProject(args) {
                     },
                 }
                 : {}),
-            projectEntity: {
-                externalKey: projectExternalKey,
-                entityType: entityTypeOverride,
-            },
+            projectEntity: projectConstruct
+                ? {
+                    externalKey: projectEntityKey,
+                    entityType: "project",
+                    subtype: isMonorepo ? "project_monorepo" : "project_repository",
+                    ...(isMonorepo ? {} : { applicationExternalKey: projectExternalKey }),
+                }
+                : {
+                    externalKey: projectExternalKey,
+                    entityType: entityTypeOverride,
+                },
             pendingSteps,
             readFiles: readmeHints,
             ...(refreshMode
@@ -1832,7 +1869,7 @@ export async function initProject(args) {
             lines.push("Until they are done, this project is registered as a skeleton only.");
         }
         lines.push("");
-        lines.push(`PROJECT : ${projectExternalKey}`);
+        lines.push(`PROJECT : ${projectConstruct ? `${projectEntityKey} (${isMonorepo ? "monorepo" : "repository"})` : projectExternalKey}`);
         lines.push(`DIR     : ${dir}`);
         if (readmeHints.length > 0) {
             lines.push("");
@@ -1861,10 +1898,15 @@ export async function initProject(args) {
                     lines.push(`    unresolved deps (${unresolvedDeps.length}): ${unresolvedDeps.slice(0, 5).join(", ")}${unresolvedDeps.length > 5 ? ` … +${unresolvedDeps.length - 5} more` : ""}`);
                 }
                 lines.push(`    1) nexarch update-entity --key "${sp.externalKey}" --entity-type "${sp.entityType}" --subtype "${sp.subtype}" --name "..." --description "..."`);
-                const rel = structuralRelForSubPackage(sp, projectExternalKey);
-                if (rel) {
-                    lines.push(`    2) nexarch add-relationship --from "${rel.from}" --to "${rel.to}" --type ${rel.type}`);
-                    lines.push(`       (adjust key prefix if you changed the entity type above)`);
+                if (projectConstruct) {
+                    lines.push(`       (sourced_from ${projectEntityKey} is wired automatically — no structural relationship needed)`);
+                }
+                else {
+                    const rel = structuralRelForSubPackage(sp, projectExternalKey);
+                    if (rel) {
+                        lines.push(`    2) nexarch add-relationship --from "${rel.from}" --to "${rel.to}" --type ${rel.type}`);
+                        lines.push(`       (adjust key prefix if you changed the entity type above)`);
+                    }
                 }
             }
         }
@@ -1892,10 +1934,16 @@ export async function initProject(args) {
         lines.push("");
         lines.push("REMAINING STEPS:");
         let step = 1;
-        lines.push(`  ${step++}. nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`);
-        if (entityTypeOverride === "application") {
-            lines.push(`     ${APPLICATION_SUBTYPE_HINT}`);
-            lines.push(`     (choose app_custom_built as the default if none of the others clearly apply)`);
+        if (projectConstruct) {
+            lines.push(`  ${step++}. nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "${projectDirName}" --description "..."`);
+            lines.push(`     (short description of what lives in this repository)`);
+        }
+        if (!projectConstruct || !isMonorepo) {
+            lines.push(`  ${step++}. nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`);
+            if (entityTypeOverride === "application") {
+                lines.push(`     ${APPLICATION_SUBTYPE_HINT}`);
+                lines.push(`     (choose app_custom_built as the default if none of the others clearly apply)`);
+            }
         }
         if (subPackages.length > 0) {
             lines.push(`  ${step++}. Update each sub-package listed under CLASSIFY_THESE above.`);
@@ -1907,19 +1955,28 @@ export async function initProject(args) {
             lines.push(`     integration_function (external connectivity), or data_function (data processing).`);
             lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them.`);
             lines.push(`     For each one found:`);
+            const fnOwnerTarget = projectConstruct && isMonorepo ? '"<owning application key from CLASSIFY_THESE>"' : `"${projectExternalKey}"`;
             lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
-            lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --to "${projectExternalKey}" --type part_of`);
+            lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --to ${fnOwnerTarget} --type part_of`);
         }
         lines.push(`  ${step++}. Scan the READMEs for platforms/SaaS not auto-detected (Vercel, Neon, Stripe, etc.).`);
         lines.push(`       For each found: nexarch resolve-names --names "..." --json  →  nexarch update-entity  →  nexarch add-relationship`);
         lines.push(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register decision_record entities.`);
         lines.push(`       nexarch update-entity --key "decision_record:${projectExternalKey.split(":")[1] ?? "project"}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`);
-        lines.push(`       nexarch add-relationship --from "decision_record:..." --to "${projectExternalKey}" --type decides`);
+        lines.push(`       nexarch add-relationship --from "decision_record:..." --to ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`);
         lines.push("");
-        lines.push("RELATIONSHIP DIRECTION RULES (for sub-packages):");
-        lines.push("  apps/* (deployable components) → parent composes → sub-application");
-        lines.push("  packages/* (shared libraries)  → parent depends_on → library");
-        lines.push("  Deps wired from manifests are already pre-wired; do not re-add unless key changed.");
+        if (projectConstruct) {
+            lines.push("RELATIONSHIP RULES:");
+            lines.push(`  Every package is sourced_from ${projectEntityKey} — wired automatically (provenance, not containment).`);
+            lines.push("  Manifest deps are pre-wired per package; do not re-add unless a key changed.");
+            lines.push("  Genuine product composition (one product spanning these apps) is a human judgement — propose it, never infer it from directory layout.");
+        }
+        else {
+            lines.push("RELATIONSHIP DIRECTION RULES (for sub-packages):");
+            lines.push("  apps/* (deployable components) → parent composes → sub-application");
+            lines.push("  packages/* (shared libraries)  → parent depends_on → library");
+            lines.push("  Deps wired from manifests are already pre-wired; do not re-add unless key changed.");
+        }
         if (refreshMode && (currentOutgoingRels.length > 0 || currentPartOfRels.length > 0)) {
             lines.push("");
             lines.push(`GRAPH_STATE (${currentOutgoingRels.length + currentPartOfRels.length} current relationships in Nexarch — compare against what the scanner detected above):`);
@@ -1943,7 +2000,18 @@ export async function initProject(args) {
         ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
         status: outputStatus,
         mode: refreshMode ? "refresh" : "init",
-        project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride, detectedEcosystems },
+        project: projectConstruct
+            ? {
+                name: projectDirName,
+                externalKey: projectEntityKey,
+                entityType: "project",
+                subtype: isMonorepo ? "project_monorepo" : "project_repository",
+                detectedEcosystems,
+                ...(isMonorepo
+                    ? { applications: subPackages.filter((sp) => sp.entityType === "application").map((sp) => sp.externalKey) }
+                    : { applicationExternalKey: projectExternalKey }),
+            }
+            : { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride, detectedEcosystems },
         entities: entitiesResult.summary ?? {},
         relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
         metrics: {

package/dist/index.js

@@ -73,195 +73,198 @@ async function main() {
     }
     const handler = commands[command ?? ""];
     if (!handler) {
-        console.log(`
-nexarch — Your architecture workspace for AI delivery.
-
-Usage:
-  nexarch login         Authenticate in browser and store company-scoped credentials
-                        Option: --company <id>
-  nexarch logout        Remove stored credentials
-  nexarch status        Check connection and show architecture summary
-  nexarch setup         One-step onboarding: login (if needed) + MCP config + register agent
-  nexarch mcp-config    Print MCP server config block for manual setup
-                        Client list is registry-managed (see 'nexarch mcp-config --client <code>')
-  nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
-  nexarch init-agent    Run handshake + mandatory agent registration in graph (advanced/manual)
-                        Options: --agent-id <id> --bind-to-external-key <key>
-                                 --bind-relationship-type <code> --redact-hostname
-                                 --json --strict
-  nexarch agent identify
-                      Capture richer coding-agent identity metadata
-                      Options: --agent-id <id> --provider <provider> --model <model>
-                               --client <name> [--framework <name>] [--session-id <id>]
-                               [--tool-version <v>] [--capabilities <csv>]
-                               [--notes <text>] [--json]
-  nexarch agent-identify
-                      Alias of 'nexarch agent identify'
-  nexarch init-project
-                      Scan a project directory, resolve detected packages/env vars/
-                      config files against the reference library, write entities and
-                      relationships to the architecture graph, and log unresolved
-                      names as reference candidates.
-                      When entity-type=application and existing applications are present,
-                      prompts to map to an existing app or create a new one.
-                      Options: --dir <path>  (default: cwd)
-                               --name <name>  override project name
-                               --entity-type <code>  (default: application)
-                               --application-ref <entityRef>  force mapping target
-                               --create-application  force new application entity
-                               --auto-map-application  auto-map only when high confidence
-                               --non-interactive  fail on ambiguous mapping
-                               --batch-size <n>  upsert batch size (default: 10)
-                               --profile  include timing/profile data in JSON output
-                               --dry-run  preview without writing
-                               --json
-  nexarch update-project
-                      Re-scan a previously registered project directory, refresh
-                      entities and relationships in the graph, and diff the new scan
-                      against the current graph state to surface stale relationships
-                      and removed sub-packages for the calling agent to review.
-                      Accepts all the same options as init-project plus:
-                               --application-ref <entityRef>  target project key (recommended)
-                               --auto-map-application  auto-select best-match application
-                      Output includes enrichmentRequired.diff with:
-                        newRelationships    — detected but not yet in graph
-                        staleRelationships  — in graph but absent from manifests
-                        removedSubPackages  — previously registered, no longer on disk
-                               --json
-  nexarch update-entity
-                      Update the name and/or description of an existing graph entity.
-                      Use this after init-project to enrich the entity with meaningful
-                      content from the project README or docs.
-                      Options: --key <externalKey>  (required)
-                               --name <name>
-                               --description <text>
-                               --entity-type <code>  (default: application)
-                               --subtype <code>
-                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
-                               --attributes-json '<json object>'
-                               --attributes-file <path.json>
-                               --json
-  nexarch add-relationship
-                      Add relationships between existing graph entities (single or batch).
-                      Single options: --from <externalKey>
-                                      --to <externalKey>
-                                      --type <code> (e.g. part_of, depends_on)
-                      Batch options:  --relationships-json '<json array>'
-                                      --relationships-file <path.json>
-                      --json
-  nexarch register-alias
-                      Register a company-scoped alias for an entity so future
-                      scans resolve it instead of logging it as a candidate.
-                      Use after enriching internal monorepo packages.
-                      Options: --alias <value>       (required, e.g. @scope/name)
-                               --key <externalKey>   (required)
-                               --name <name>         (required)
-                               --entity-type <code>  (required)
-                               --subtype <code>
-                               --description <text>
-                               --json
-  nexarch resolve-names
-                      Look up one or more raw names (package names, platform
-                      names) against the global reference library and return
-                      their canonical external keys. Useful for gap-check
-                      results before calling add-relationship.
-                      Options: --names <csv>  (required, e.g. "vercel,neon")
-                               --json
-  nexarch list-entities
-                      List entities from the workspace graph.
-                      Options: --type <entityTypeCode>
-                               --status <status>
-                               --query <text>
-                               --limit <1-500>
-                               --json
-  nexarch list-relationships
-                      List relationships from the workspace graph.
-                      Options: --type <relationshipTypeCode>
-                               --status <status>
-                               --from <fromExternalKey>
-                               --to <toExternalKey>
-                               --limit <1-500>
-                               --json
-  nexarch register-runtime
-                      Register or refresh runtime + optional application context
-                      without performing check-in.
-                      Options: --application-ref <entityRef>
-                               --client <name>
-                               --version <semver>
-                               --json
-  nexarch check-in    Preview pending application-target commands (no auto-claim)
-                      and report draft/proposed applications needing review so the
-                      agent can prompt the user to explore and instantiate them.
-                      Use command-claim to explicitly claim a specific command.
-                      Scope is resolved server-side from active company context.
-                      Options: --agent-key <key>   override stored agent key
-                               --application-ref <entityRef>  narrow preview scope
-                               --json              JSON output includes draftApplications[] and proposedApplications[]
-  nexarch proposals start
-                      Start a new application workspace from a proposed NexArch app.
-                      Lists proposed apps, shows policy review gates, writes a starter
-                      project scaffold, and activates the proposal to active once
-                      required policy controls are acknowledged.
-                      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.
-                      Options: --id <commandId>    (required)
-                               --agent-key <key>   override stored agent key
-                               --application-ref <entityRef>  required for application-target commands
-                               --json
-  nexarch command-done
-                      Mark a claimed command as completed.
-                      Options: --id <commandId>    (required)
-                               --summary <text>    short summary of what was done
-                               --summary-file <path.md|txt>
-                               --json
-  nexarch command-fail
-                      Mark a claimed command as failed.
-                      Options: --id <commandId>    (required)
-                               --error <message>   (required)
-                               --json
-  nexarch policy-controls
-                      Fetch policy controls/rules assigned to an entity (for policy audits).
-                      Options: --entity <externalKey>  (required, e.g. application:bad-driving)
-                               --json
-  nexarch policy-audit-template
-                      Generate a findings JSON template from policy controls/rules for an entity.
-                      Options: --entity <externalKey>   (required)
-                               --control-id <uuid>      (repeatable; optional filter)
-                               --default-result <pass|partial|fail> (default: fail)
-                               --output <path.json>
-                               --json
-  nexarch policy-audit-submit
-                      Submit structured policy findings (writes policy_audit_finding rows).
-                      Options: --command-id <id>        (required)
-                               --application-key <key>  (required)
-                               --agent-key <key>        (optional; defaults from identity)
-                               --finding <controlId|ruleId|result|rationale|missing1;missing2> (repeatable)
-                               --findings-json <json-array>
-                               --findings-file <path.json>
-                               --json
-  nexarch policy-audit-results
-                      Retrieve stored results of previous policy audits for an application.
-                      Options: --entity <applicationEntityRef>  (required)
-                               --limit <1-10>                   (default 1)
-                               --json
-  nexarch applied-policies
-                      List policy documents applied to this company account.
-                      Options: --pack <packCode>  filter to a specific pack
-                               --markdown        include full document markdown
-                               --json
-  nexarch governance-summary
-                      Print review queue, graph stats, and per-application policy
-                      audit rollup (latest run status, pass/partial/fail counts).
-                      Options: --json
+        console.log(`
+nexarch — Your architecture workspace for AI delivery.
+
+Usage:
+  nexarch login         Authenticate in browser and store company-scoped credentials
+                        Option: --company <id>
+  nexarch logout        Remove stored credentials
+  nexarch status        Check connection and show architecture summary
+  nexarch setup         One-step onboarding: login (if needed) + MCP config + register agent
+  nexarch mcp-config    Print MCP server config block for manual setup
+                        Client list is registry-managed (see 'nexarch mcp-config --client <code>')
+  nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
+  nexarch init-agent    Run handshake + mandatory agent registration in graph (advanced/manual)
+                        Options: --agent-id <id> --bind-to-external-key <key>
+                                 --bind-relationship-type <code> --redact-hostname
+                                 --json --strict
+  nexarch agent identify
+                      Capture richer coding-agent identity metadata
+                      Options: --agent-id <id> --provider <provider> --model <model>
+                               --client <name> [--framework <name>] [--session-id <id>]
+                               [--tool-version <v>] [--capabilities <csv>]
+                               [--notes <text>] [--json]
+  nexarch agent-identify
+                      Alias of 'nexarch agent identify'
+  nexarch init-project
+                      Scan a project directory, resolve detected packages/env vars/
+                      config files against the reference library, write entities and
+                      relationships to the architecture graph, and log unresolved
+                      names as reference candidates.
+                      Monorepos register a project entity plus one proposed
+                      application per deployable package (sourced_from the project).
+                      Single-package repos register the repo's one application; when
+                      similar applications exist they are listed, and the new
+                      application is created as proposed for review at activation.
+                      Options: --dir <path>  (default: cwd)
+                               --name <name>  override project name
+                               --entity-type <code>  (default: application)
+                               --application-ref <entityRef>  force mapping target
+                               --create-application  force new application entity
+                               --auto-map-application  auto-map only when high confidence
+                               --non-interactive  deprecated (mapping no longer prompts)
+                               --batch-size <n>  upsert batch size (default: 10)
+                               --profile  include timing/profile data in JSON output
+                               --dry-run  preview without writing
+                               --json
+  nexarch update-project
+                      Re-scan a previously registered project directory, refresh
+                      entities and relationships in the graph, and diff the new scan
+                      against the current graph state to surface stale relationships
+                      and removed sub-packages for the calling agent to review.
+                      Accepts all the same options as init-project plus:
+                               --application-ref <entityRef>  target project key (recommended)
+                               --auto-map-application  auto-select best-match application
+                      Output includes enrichmentRequired.diff with:
+                        newRelationships    — detected but not yet in graph
+                        staleRelationships  — in graph but absent from manifests
+                        removedSubPackages  — previously registered, no longer on disk
+                               --json
+  nexarch update-entity
+                      Update the name and/or description of an existing graph entity.
+                      Use this after init-project to enrich the entity with meaningful
+                      content from the project README or docs.
+                      Options: --key <externalKey>  (required)
+                               --name <name>
+                               --description <text>
+                               --entity-type <code>  (default: application)
+                               --subtype <code>
+                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
+                               --attributes-json '<json object>'
+                               --attributes-file <path.json>
+                               --json
+  nexarch add-relationship
+                      Add relationships between existing graph entities (single or batch).
+                      Single options: --from <externalKey>
+                                      --to <externalKey>
+                                      --type <code> (e.g. part_of, depends_on)
+                      Batch options:  --relationships-json '<json array>'
+                                      --relationships-file <path.json>
+                      --json
+  nexarch register-alias
+                      Register a company-scoped alias for an entity so future
+                      scans resolve it instead of logging it as a candidate.
+                      Use after enriching internal monorepo packages.
+                      Options: --alias <value>       (required, e.g. @scope/name)
+                               --key <externalKey>   (required)
+                               --name <name>         (required)
+                               --entity-type <code>  (required)
+                               --subtype <code>
+                               --description <text>
+                               --json
+  nexarch resolve-names
+                      Look up one or more raw names (package names, platform
+                      names) against the global reference library and return
+                      their canonical external keys. Useful for gap-check
+                      results before calling add-relationship.
+                      Options: --names <csv>  (required, e.g. "vercel,neon")
+                               --json
+  nexarch list-entities
+                      List entities from the workspace graph.
+                      Options: --type <entityTypeCode>
+                               --status <status>
+                               --query <text>
+                               --limit <1-500>
+                               --json
+  nexarch list-relationships
+                      List relationships from the workspace graph.
+                      Options: --type <relationshipTypeCode>
+                               --status <status>
+                               --from <fromExternalKey>
+                               --to <toExternalKey>
+                               --limit <1-500>
+                               --json
+  nexarch register-runtime
+                      Register or refresh runtime + optional application context
+                      without performing check-in.
+                      Options: --application-ref <entityRef>
+                               --client <name>
+                               --version <semver>
+                               --json
+  nexarch check-in    Preview pending application-target commands (no auto-claim)
+                      and report draft/proposed applications needing review so the
+                      agent can prompt the user to explore and instantiate them.
+                      Use command-claim to explicitly claim a specific command.
+                      Scope is resolved server-side from active company context.
+                      Options: --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  narrow preview scope
+                               --json              JSON output includes draftApplications[] and proposedApplications[]
+  nexarch proposals start
+                      Start a new application workspace from a proposed NexArch app.
+                      Lists proposed apps, shows policy review gates, writes a starter
+                      project scaffold, and activates the proposal to active once
+                      required policy controls are acknowledged.
+                      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.
+                      Options: --id <commandId>    (required)
+                               --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  required for application-target commands
+                               --json
+  nexarch command-done
+                      Mark a claimed command as completed.
+                      Options: --id <commandId>    (required)
+                               --summary <text>    short summary of what was done
+                               --summary-file <path.md|txt>
+                               --json
+  nexarch command-fail
+                      Mark a claimed command as failed.
+                      Options: --id <commandId>    (required)
+                               --error <message>   (required)
+                               --json
+  nexarch policy-controls
+                      Fetch policy controls/rules assigned to an entity (for policy audits).
+                      Options: --entity <externalKey>  (required, e.g. application:bad-driving)
+                               --json
+  nexarch policy-audit-template
+                      Generate a findings JSON template from policy controls/rules for an entity.
+                      Options: --entity <externalKey>   (required)
+                               --control-id <uuid>      (repeatable; optional filter)
+                               --default-result <pass|partial|fail> (default: fail)
+                               --output <path.json>
+                               --json
+  nexarch policy-audit-submit
+                      Submit structured policy findings (writes policy_audit_finding rows).
+                      Options: --command-id <id>        (required)
+                               --application-key <key>  (required)
+                               --agent-key <key>        (optional; defaults from identity)
+                               --finding <controlId|ruleId|result|rationale|missing1;missing2> (repeatable)
+                               --findings-json <json-array>
+                               --findings-file <path.json>
+                               --json
+  nexarch policy-audit-results
+                      Retrieve stored results of previous policy audits for an application.
+                      Options: --entity <applicationEntityRef>  (required)
+                               --limit <1-10>                   (default 1)
+                               --json
+  nexarch applied-policies
+                      List policy documents applied to this company account.
+                      Options: --pack <packCode>  filter to a specific pack
+                               --markdown        include full document markdown
+                               --json
+  nexarch governance-summary
+                      Print review queue, graph stats, and per-application policy
+                      audit rollup (latest run status, pass/partial/fail counts).
+                      Options: --json
     `);
         process.exit(command ? 1 : 0);
     }

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "nexarch",
-  "version": "0.12.4",
-  "description": "Your architecture workspace for AI delivery.",
-  "keywords": [
-    "nexarch",
-    "mcp",
-    "architecture",
-    "ai"
-  ],
-  "license": "MIT",
-  "author": "Nexarch <hello@nexarch.ai>",
-  "homepage": "https://nexarch.ai",
-  "engines": {
-    "node": ">=18"
-  },
-  "type": "module",
-  "bin": {
-    "nexarch": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "tsc",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "tsx": "^4",
-    "typescript": "^5"
-  }
-}
+{
+  "name": "nexarch",
+  "version": "0.12.6",
+  "description": "Your architecture workspace for AI delivery.",
+  "keywords": [
+    "nexarch",
+    "mcp",
+    "architecture",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Nexarch <hello@nexarch.ai>",
+  "homepage": "https://nexarch.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "nexarch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}