nexarch 0.12.4 → 0.12.5

package/dist/commands/init-project.js

@@ -1162,20 +1162,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 +1226,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,7 +1283,10 @@ 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)
@@ -1343,7 +1359,7 @@ export async function initProject(args) {
             }
         }
     }
-    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 +1392,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 +1448,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 +1477,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 +1530,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 +1553,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 +1603,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 +1709,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 +1762,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 +1773,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 +1782,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 +1805,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 +1919,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 +1948,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 +1984,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 +2005,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 +2050,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/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.5",
+  "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"
+  }
+}