@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/core/model-upgrade.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/core/model-upgrade.ts"],
+  "sourcesContent": ["/**\n * Model upgrade - moves a model to a newer spec version and keeps its staged changesets\n * committable.\n *\n * A staged changeset records a hash of the model it was created on (its base snapshot), and\n * committing it fails while the model no longer has that hash. An upgrade always changes the\n * hash: it writes a new spec version into the manifest, and migrations may rewrite element\n * files. So the upgrade re-baselines each staged changeset that was in step with the model\n * before the upgrade onto the upgraded model. A changeset that had drifted before the upgrade\n * keeps its base snapshot, so that drift still blocks its commit.\n */\n\nimport { readdir } from \"fs/promises\";\nimport { Model } from \"./model.js\";\nimport { MigrationRegistry, type ApplyMigrationsResult } from \"./migration-registry.js\";\nimport { applyCatalogMigrations } from \"./catalog-migration.js\";\nimport { BaseSnapshotManager } from \"./base-snapshot-manager.js\";\nimport { StagedChangesetStorage } from \"./staged-changeset-storage.js\";\nimport { FileLock } from \"../utils/file-lock.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\n\nexport interface ModelUpgradeOptions {\n  fromVersion: string;\n  toVersion: string;\n  /** No migration path exists between the versions: only write the new spec version */\n  versionBumpOnly?: boolean;\n  /**\n   * The model is at the target version but still names retired types or relationships: apply\n   * the catalog migration (element type renames and relationship rewrites) on its own\n   */\n  catalogOnly?: boolean;\n  /** Passed to the migrations (default true) */\n  validate?: boolean;\n}\n\n/** A staged changeset, by directory id and name */\nexport interface ChangesetRef {\n  id: string;\n  name: string;\n}\n\nexport interface ChangesetRebaselineResult {\n  /** Staged changesets now based on the upgraded model */\n  rebaselined: ChangesetRef[];\n  /** Staged changesets that had drifted before the upgrade; they keep their base snapshot */\n  drifted: ChangesetRef[];\n  /** Changesets that could not be read or re-baselined */\n  errors: string[];\n}\n\nexport interface ModelUpgradeResult {\n  /** The migrations applied; absent for a version bump */\n  migration?: ApplyMigrationsResult;\n  changesets: ChangesetRebaselineResult;\n}\n\n/** Staged changesets sorted by whether they match the model before an upgrade */\nexport interface ChangesetBaselines {\n  /** Snapshot of the model before the upgrade; null when there is no staged changeset */\n  snapshot: string | null;\n  inStep: ChangesetRef[];\n  drifted: ChangesetRef[];\n  errors: string[];\n}\n\n/**\n * Upgrade the model at startPath to options.toVersion and save it, then re-baseline its\n * staged changesets on the upgraded model.\n */\nexport async function upgradeModel(\n  startPath: string,\n  options: ModelUpgradeOptions\n): Promise<ModelUpgradeResult> {\n  // Load every layer, as `dr changeset commit` does before it checks for drift\n  const model = await Model.load(startPath, { lazyLoad: false });\n  const baselines = await captureChangesetBaselines(model);\n\n  let migration: ApplyMigrationsResult | undefined;\n  if (options.versionBumpOnly) {\n    model.manifest.specVersion = options.toVersion;\n    await model.saveManifest();\n  } else if (options.catalogOnly) {\n    const catalog = await applyCatalogMigrations(model);\n    if (catalog.errors.length > 0) {\n      throw new Error(`Catalog migration failed: ${catalog.errors.join(\"; \")}`);\n    }\n    migration = {\n      applied: [\n        {\n          from: options.fromVersion,\n          to: options.toVersion,\n          description: `Catalog changes applied (${catalog.summaries.join(\"; \")})`,\n          changes: {\n            migrationsApplied: 1,\n            filesModified: catalog.filesModified,\n            description: catalog.summaries.join(\"; \"),\n            details: catalog.details,\n          },\n        },\n      ],\n      currentVersion: options.fromVersion,\n      targetVersion: options.toVersion,\n      totalChanges: 1,\n    };\n    await model.saveDirtyLayers();\n  } else {\n    migration = await new MigrationRegistry().applyMigrations(model, {\n      fromVersion: options.fromVersion,\n      toVersion: options.toVersion,\n      dryRun: false,\n      validate: options.validate ?? true,\n    });\n    await model.saveManifest();\n    await model.saveDirtyLayers();\n  }\n\n  return { migration, changesets: await rebaselineChangesets(startPath, baselines) };\n}\n\n/**\n * Hash the model and sort its staged changesets into those whose base snapshot matches it\n * and those that had drifted from it. Call before the model changes.\n *\n * @param model - loaded with lazyLoad: false, as `dr changeset commit` loads it, because the\n *   snapshot hashes every loaded layer\n */\nexport async function captureChangesetBaselines(model: Model): Promise<ChangesetBaselines> {\n  if (model.lazyLoad) {\n    throw new Error(\"captureChangesetBaselines needs a model loaded with lazyLoad: false\");\n  }\n\n  const { changesets, errors } = await listStagedChangesets(model.rootPath);\n  const baselines: ChangesetBaselines = { snapshot: null, inStep: [], drifted: [], errors };\n  if (changesets.length === 0) {\n    return baselines;\n  }\n\n  const snapshot = await new BaseSnapshotManager().captureSnapshot(model);\n  baselines.snapshot = snapshot;\n  for (const { ref, baseSnapshot } of changesets) {\n    // A changeset without a base snapshot never reports drift, so it needs no re-baseline\n    if (!baseSnapshot) {\n      continue;\n    }\n    (baseSnapshot === snapshot ? baselines.inStep : baselines.drifted).push(ref);\n  }\n  return baselines;\n}\n\n/**\n * Point the changesets that were in step before the upgrade at the upgraded model. Call after\n * the upgraded model is saved.\n *\n * @param startPath - the path the model was loaded from before the upgrade\n */\nexport async function rebaselineChangesets(\n  startPath: string,\n  baselines: ChangesetBaselines\n): Promise<ChangesetRebaselineResult> {\n  const result: ChangesetRebaselineResult = {\n    rebaselined: [],\n    drifted: baselines.drifted,\n    errors: [...baselines.errors],\n  };\n  if (baselines.inStep.length === 0) {\n    return result;\n  }\n\n  // Reload rather than hash the model in memory: migrations may rewrite files on disk\n  // without updating it, and the commit hashes what it loads from disk\n  const upgraded = await Model.load(startPath, { lazyLoad: false });\n  const snapshot = await new BaseSnapshotManager().captureSnapshot(upgraded);\n  const storage = new StagedChangesetStorage(upgraded.rootPath);\n\n  for (const ref of baselines.inStep) {\n    try {\n      await new FileLock(storage.getChangesetPath(ref.id)).withLock(async () => {\n        const changeset = await storage.load(ref.id);\n        // Skip a changeset whose status or base changed while the upgrade ran\n        if (\n          !changeset ||\n          changeset.status !== \"staged\" ||\n          changeset.baseSnapshot !== baselines.snapshot\n        ) {\n          return;\n        }\n        changeset.baseSnapshot = snapshot;\n        changeset.updateModified();\n        await storage.save(changeset);\n        result.rebaselined.push(ref);\n      });\n    } catch (error) {\n      result.errors.push(\n        `Could not re-baseline changeset '${ref.name}': ${getErrorMessage(error)}; committing it needs --force`\n      );\n    }\n  }\n  return result;\n}\n\nasync function listStagedChangesets(rootPath: string): Promise<{\n  changesets: Array<{ ref: ChangesetRef; baseSnapshot: string | undefined }>;\n  errors: string[];\n}> {\n  const storage = new StagedChangesetStorage(rootPath);\n  const changesets: Array<{ ref: ChangesetRef; baseSnapshot: string | undefined }> = [];\n  const errors: string[] = [];\n\n  let ids: string[];\n  try {\n    ids = (await readdir(storage.getChangesetsDir(), { withFileTypes: true }))\n      // FileLock keeps \"<changeset>.lock\" directories beside the changesets\n      .filter((entry) => entry.isDirectory() && !entry.name.endsWith(\".lock\"))\n      .map((entry) => entry.name)\n      .sort();\n  } catch (error) {\n    if ((error as { code?: string }).code !== \"ENOENT\") {\n      errors.push(`Could not list changesets: ${getErrorMessage(error)}`);\n    }\n    return { changesets, errors };\n  }\n\n  for (const id of ids) {\n    try {\n      const changeset = await storage.load(id);\n      if (changeset?.status === \"staged\") {\n        changesets.push({\n          ref: { id, name: changeset.name || id },\n          baseSnapshot: changeset.baseSnapshot,\n        });\n      }\n    } catch (error) {\n      errors.push(`Could not read changeset '${id}': ${getErrorMessage(error)}`);\n    }\n  }\n  return { changesets, errors };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/core/model.js

@@ -10,6 +10,9 @@ import { ensureDir, writeFile } from "../utils/file-io.js";
 import { getCliVersion } from "../utils/spec-version.js";
 import { startSpan, endSpan, startActiveSpan } from "../telemetry/index.js";
 import { findProjectRoot } from "../utils/project-paths.js";
+import { getCodebasePath } from "../utils/globals.js";
+import { getErrorMessage } from "../utils/errors.js";
+import { assertBaseModelWritable } from "./changeset-only-guard.js";
 import { getNodeType } from "../generated/node-types.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -49,19 +52,26 @@ function isPersistableAttribute(specNodeId, key) {
 const isTelemetryEnabled = !1;
 class Model {
   rootPath;
+  codebaseRoot;
   manifest;
   graph;
   layers;
   relationships;
   lazyLoad;
+  loadedLayerFilter;
   loadedLayers;
   virtualProjectionEngine;
   /** ID of the currently active changeset, or null if none is active. Set during load(). */
   _activeChangesetId = null;
   /** Layer names that exist only in staged changes (not yet committed to base model). */
   _stagedLayerNames = /* @__PURE__ */ new Set();
+  /**
+   * relationships.yaml as committed, captured at load time before the active changeset's staged
+   * relationship changes are merged into `relationships`. Null when no changeset was active.
+   */
+  _baseRelationships = null;
   constructor(rootPath, manifest, options = {}) {
-    this.rootPath = rootPath, this.manifest = manifest, this.graph = new GraphModel(), this.layers = /* @__PURE__ */ new Map(), this.relationships = new Relationships(), this.lazyLoad = options.lazyLoad ?? !1, this.loadedLayers = /* @__PURE__ */ new Set();
+    this.rootPath = rootPath, this.codebaseRoot = options.codebaseRoot ?? rootPath, this.manifest = manifest, this.graph = new GraphModel(), this.layers = /* @__PURE__ */ new Map(), this.relationships = new Relationships(), this.lazyLoad = options.lazyLoad ?? !1, this.loadedLayerFilter = options.layers, this.loadedLayers = /* @__PURE__ */ new Set();
   }
   /**
    * Get the committed base layer (no staging projection).
@@ -79,8 +89,11 @@ class Model {
     if (this.lazyLoad && !this.loadedLayers.has(name) && await this.loadLayer(name), this._activeChangesetId)
       try {
         return await this.getVirtualProjectionEngine().projectLayer(this, this._activeChangesetId, name);
-      } catch {
-        return this.layers.get(name);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err), isChangesetNotFound = errorMessage.includes("Changeset") && errorMessage.includes("not found"), isCorrupted = errorMessage.includes("corrupted");
+        if (isChangesetNotFound || isCorrupted)
+          return this.layers.get(name);
+        throw err;
       }
     return this.layers.get(name);
   }
@@ -108,18 +121,34 @@ class Model {
   getActiveChangesetId() {
     return this._activeChangesetId;
   }
+  /**
+   * The committed relationships, without the active changeset's staged additions and removals
+   * that load() merges into `relationships` for read commands. Equal to `relationships.getAll()`
+   * when no changeset was active at load time.
+   */
+  getBaseRelationships() {
+    return this._baseRelationships ? [...this._baseRelationships] : this.relationships.getAll();
+  }
   /**
    * Load a layer from disk (model/XX_layername/*.yaml files)
    */
   async loadLayer(name) {
     await startActiveSpan("layer.load", async (layerSpan) => {
       const fs2 = await import("fs/promises"), yaml = await import("yaml");
-      let layerPath = null;
-      const modelDir = `${this.rootPath}/documentation-robotics/model`;
+      let layerPath = null, modelDir = `${this.rootPath}/documentation-robotics/model`;
       try {
         const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
         layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
-      } catch {
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
+        try {
+          const layerDir = (await fs2.readdir(this.rootPath, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
+          layerDir && (layerPath = `${this.rootPath}/${layerDir.name}`);
+        } catch (err2) {
+          if (!(err2?.code === "ENOENT"))
+            throw err2;
+        }
       }
       if (!layerPath)
         return;
@@ -211,10 +240,19 @@ class Model {
     const staged = Array.from(this._stagedLayerNames).filter((l) => !this.layers.has(l));
     return [...base, ...staged];
   }
+  /**
+   * Records that the active changeset now stages an element change in `layerName`, so
+   * getLayerNames() (and findElementLayer()) discover a layer the base model does not have without
+   * a reload. StagingAreaManager calls this when it stages into this model's active changeset.
+   */
+  noteStagedLayer(changesetId, layerName) {
+    this._activeChangesetId && this._activeChangesetId === changesetId && layerName && this._stagedLayerNames.add(layerName);
+  }
   /**
    * Save a layer to disk (model/XX_layername/*.yaml)
    */
   async saveLayer(name) {
+    assertBaseModelWritable();
     const layer = this.layers.get(name);
     if (!layer)
       throw new Error(`Layer ${name} not found`);
@@ -224,7 +262,16 @@ class Model {
     try {
       const layerDir = (await fs2.readdir(modelDir, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
       layerDir && (layerPath = `${modelDir}/${layerDir.name}`);
-    } catch {
+    } catch (err) {
+      if (!(err?.code === "ENOENT"))
+        throw err;
+      try {
+        const layerDir = (await fs2.readdir(this.rootPath, { withFileTypes: !0 })).find((e) => e.isDirectory() && e.name.match(/^\d{2}_/) && e.name.replace(/^\d{2}_/, "") === name);
+        layerDir && (layerPath = `${this.rootPath}/${layerDir.name}`);
+      } catch (err2) {
+        if (!(err2?.code === "ENOENT"))
+          throw err2;
+      }
     }
     if (!layerPath) {
       const layerNameWithoutPrefix = name.replace(/^\d{2}-/, ""), index = CANONICAL_LAYER_NAMES.indexOf(layerNameWithoutPrefix);
@@ -302,7 +349,7 @@ class Model {
    * Save the manifest to disk (documentation-robotics/model/manifest.yaml)
    */
   async saveManifest() {
-    this.manifest.updateModified();
+    assertBaseModelWritable(), this.manifest.updateModified();
     const yaml = await import("yaml"), manifestPath = `${this.rootPath}/documentation-robotics/model/manifest.yaml`, yamlData = {
       version: this.manifest.version,
       schema: "documentation-robotics-v1",
@@ -328,7 +375,7 @@ class Model {
         ...layer && { elements: this.getLayerElementCounts(layer) }
       };
     }
-    this.manifest.changeset_history && this.manifest.changeset_history.length > 0 && (yamlData.changeset_history = this.manifest.changeset_history), await ensureDir(`${this.rootPath}/documentation-robotics/model`), await writeFile(manifestPath, yaml.stringify(yamlData));
+    this.manifest.codebase_path && (yamlData.codebase_path = this.manifest.codebase_path), this.manifest.changeset_history && this.manifest.changeset_history.length > 0 && (yamlData.changeset_history = this.manifest.changeset_history), this.manifest.models && Object.keys(this.manifest.models).length > 0 && (yamlData.models = this.manifest.models), await ensureDir(`${this.rootPath}/documentation-robotics/model`), await writeFile(manifestPath, yaml.stringify(yamlData));
   }
   getLayerElementCounts(layer) {
     const counts = {};
@@ -350,8 +397,8 @@ class Model {
         throw new Error(`Failed to load relationships.yaml: ${err instanceof Error ? err.message : String(err)}`);
       return;
     }
-    if (!Array.isArray(data)) {
-      console.warn(`Warning: relationships.yaml contains non-array content (received ${data === null ? "null" : typeof data}). Expected an array of relationships. Skipping relationship loading.`);
+    if (data === null && (data = []), !Array.isArray(data)) {
+      console.warn(`Warning: relationships.yaml contains non-array content (received ${typeof data}). Expected an array of relationships. Skipping relationship loading.`);
       return;
     }
     this.relationships = Relationships.fromArray(data);
@@ -372,17 +419,86 @@ class Model {
   }
   /**
    * Save relationships to relationships.yaml
+   *
+   * @param options.preserveHeader - Keep the file's existing leading comment block
+   *   (refreshing its `# Last updated:` line) instead of writing the standard header.
    */
-  async saveRelationships() {
+  async saveRelationships(options = {}) {
+    assertBaseModelWritable();
     const fs2 = await import("fs/promises"), yaml = await import("yaml"), relationshipsPath = `${this.rootPath}/documentation-robotics/model/relationships.yaml`;
     await ensureDir(`${this.rootPath}/documentation-robotics/model`);
-    const data = this.relationships.toArray(), yamlContent = `# Intra-layer relationships
+    const data = this.relationships.toArray(), timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    let header = `# Intra-layer relationships
 # Format: source_id -> predicate -> target_id
-# Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}
+# Last updated: ${timestamp}
 
-` + yaml.stringify(data);
+`;
+    if (options.preserveHeader)
+      try {
+        const { extractRelationshipsHeader } = await import("./relationship-prune.js"), existing = extractRelationshipsHeader(await fs2.readFile(relationshipsPath, "utf-8"));
+        existing && (header = existing.replace(/^(# Last updated:).*$/m, `$1 ${timestamp}`) + `
+`);
+      } catch {
+      }
+    const yamlContent = header + yaml.stringify(data);
     await fs2.writeFile(relationshipsPath, yamlContent, "utf-8"), this.relationships.markClean();
   }
+  /**
+   * Auto-resolve codebaseRoot from farm manifest if inside a farm
+   *
+   * @param modelRoot - The model's project root (documentation_robotics parent)
+   * @returns Resolved codebase root path, or null if not in farm or resolution fails
+   */
+  static async resolveFarmCodebaseRoot(modelRoot) {
+    const { findFarmRoot } = await import("../utils/project-paths.js"), { FarmManifest } = await import("./farm-manifest.js"), farmRoot = await findFarmRoot(modelRoot);
+    if (!farmRoot)
+      return null;
+    const farmYamlPath = path.join(farmRoot, "farm.yaml");
+    let manifest;
+    try {
+      manifest = await FarmManifest.load(farmYamlPath);
+    } catch (error) {
+      const errorMsg = getErrorMessage(error);
+      if (errorMsg.includes("ENOENT") || errorMsg.includes("not found"))
+        return null;
+      throw new Error(`Failed to load farm manifest at ${farmYamlPath}: ${errorMsg}`);
+    }
+    const modelName = path.basename(modelRoot);
+    for (const project of manifest.getAllProjects())
+      if (path.basename(project.model) === modelName)
+        return path.resolve(farmRoot, project.source);
+    return null;
+  }
+  /**
+   * Walk upward from startPath looking for documentation-robotics/model/manifest.yaml,
+   * stopping at the nearest .git directory (repo boundary) so this can never cross into
+   * an unrelated parent project or a sibling farm/detached model directory.
+   *
+   * @param startPath - Directory to start the walk from
+   * @returns Manifest path if found within the repo boundary, or null
+   */
+  static async findManifestUpwardBounded(startPath) {
+    let currentPath = startPath;
+    for (; ; ) {
+      const candidateManifestPath = path.join(currentPath, "documentation-robotics", "model", "manifest.yaml");
+      try {
+        return await fs.access(candidateManifestPath), candidateManifestPath;
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
+      }
+      try {
+        return await fs.access(path.join(currentPath, ".git")), null;
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
+      }
+      const parentPath = path.dirname(currentPath);
+      if (parentPath === currentPath)
+        return null;
+      currentPath = parentPath;
+    }
+  }
   /**
    * Resolve model paths (private helper)
    *
@@ -390,18 +506,52 @@ class Model {
    * @returns Project root and manifest path
    */
   static async resolveModelPaths(startPath) {
-    const searchPath = startPath || process.cwd();
+    if (startPath) {
+      const resolvedPath = path.resolve(startPath);
+      let manifestPath2;
+      resolvedPath.endsWith("manifest.yaml") ? manifestPath2 = resolvedPath : resolvedPath.endsWith("model") ? manifestPath2 = path.join(resolvedPath, "manifest.yaml") : manifestPath2 = path.join(resolvedPath, "documentation-robotics", "model", "manifest.yaml");
+      try {
+        await fs.access(manifestPath2);
+        let projectRoot2;
+        const manifestParentDir = path.dirname(manifestPath2), standardProjectRoot = path.dirname(path.dirname(path.dirname(manifestPath2))), standardDocRobotsPath = path.join(standardProjectRoot, "documentation-robotics", "model");
+        try {
+          await fs.access(standardDocRobotsPath), projectRoot2 = standardProjectRoot;
+        } catch (err) {
+          if (!(err?.code === "ENOENT"))
+            throw err;
+          projectRoot2 = manifestParentDir;
+        }
+        return { projectRoot: projectRoot2, manifestPath: path.normalize(manifestPath2) };
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
+        const fallbackManifestPath = await Model.findManifestUpwardBounded(resolvedPath);
+        if (fallbackManifestPath)
+          return { projectRoot: path.dirname(path.dirname(path.dirname(fallbackManifestPath))), manifestPath: path.normalize(fallbackManifestPath) };
+        throw new Error(`Model not found at ${startPath}`);
+      }
+    }
     if (process.env.DR_MODEL_PATH) {
       const envPath = path.resolve(process.env.DR_MODEL_PATH);
       let manifestPath2;
       envPath.endsWith("manifest.yaml") ? manifestPath2 = envPath : envPath.endsWith("model") ? manifestPath2 = path.join(envPath, "manifest.yaml") : manifestPath2 = path.join(envPath, "documentation-robotics", "model", "manifest.yaml");
       try {
-        return await fs.access(manifestPath2), { projectRoot: path.dirname(path.dirname(path.dirname(manifestPath2))), manifestPath: path.normalize(manifestPath2) };
-      } catch {
-        throw new Error(`Model not found at DR_MODEL_PATH: ${process.env.DR_MODEL_PATH}`);
+        await fs.access(manifestPath2);
+        let projectRoot2;
+        const manifestParentDir = path.dirname(manifestPath2), standardProjectRoot = path.dirname(path.dirname(path.dirname(manifestPath2))), standardDocRobotsPath = path.join(standardProjectRoot, "documentation-robotics", "model");
+        try {
+          await fs.access(standardDocRobotsPath), projectRoot2 = standardProjectRoot;
+        } catch (err) {
+          if (!(err?.code === "ENOENT"))
+            throw err;
+          projectRoot2 = manifestParentDir;
+        }
+        return { projectRoot: projectRoot2, manifestPath: path.normalize(manifestPath2) };
+      } catch (err) {
+        throw err?.code === "ENOENT" ? new Error(`Model not found at DR_MODEL_PATH: ${process.env.DR_MODEL_PATH}`) : err;
       }
     }
-    const projectRoot = await findProjectRoot(searchPath);
+    const searchPath = process.cwd(), projectRoot = await findProjectRoot(searchPath);
     if (!projectRoot)
       throw new Error(`No DR project found. Could not find documentation_robotics/ folder.
 Run "dr init" to create a new project, or navigate to a directory containing a DR project.`);
@@ -413,6 +563,21 @@ Run "dr init" to create a new project, or navigate to a directory containing a D
 Run "dr init" to create a model.`);
     }
   }
+  /**
+   * Validate that the manifest's models field is a plain object.
+   *
+   * @param models - The raw value from manifest YAML
+   * @returns Validation result with valid flag and error message if invalid
+   */
+  static validateModelsField(models) {
+    return models == null ? { valid: !0 } : typeof models != "object" || Array.isArray(models) ? {
+      valid: !1,
+      error: `Invalid manifest 'models' field: expected an object with model names as keys (e.g., { "auth-service": { } }), but got ${Array.isArray(models) ? "an array" : `a ${typeof models}`}. This often happens when YAML syntax is incorrect, like writing 'models: auth-service' instead of 'models: { auth-service: {} }' or 'models:\\n  auth-service: {}'.`
+    } : Object.getPrototypeOf(models) !== Object.prototype ? {
+      valid: !1,
+      error: `Invalid manifest 'models' field: expected a plain object, but got an instance of ${models.constructor?.name || "unknown"}. Please ensure 'models' is a simple YAML object mapping model names to declarations.`
+    } : { valid: !0 };
+  }
   /**
    * Load a model from disk
    *
@@ -432,10 +597,34 @@ Run "dr init" to create a model.`);
         name: manifestYaml.project?.name || "Unnamed Model",
         description: manifestYaml.project?.description || "",
         version: manifestYaml.project?.version || manifestYaml.version || "0.1.0",
+        cliVersion: manifestYaml.cli_version,
         specVersion: manifestYaml.spec_version || "0.6.0",
         created: manifestYaml.created || (/* @__PURE__ */ new Date()).toISOString(),
         modified: manifestYaml.updated || (/* @__PURE__ */ new Date()).toISOString()
-      }, manifest = new Manifest(manifestData), model = new Model(projectRoot, manifest, options);
+      };
+      if (manifestYaml.models) {
+        const modelsValidation = Model.validateModelsField(manifestYaml.models);
+        if (!modelsValidation.valid)
+          throw new Error(modelsValidation.error);
+        manifestData.models = manifestYaml.models;
+      }
+      manifestYaml.codebase_path && (manifestData.codebase_path = manifestYaml.codebase_path);
+      const manifest = new Manifest(manifestData);
+      let codebaseRoot = projectRoot;
+      if (options.codebaseRoot)
+        codebaseRoot = options.codebaseRoot;
+      else {
+        const globalCodebasePath = getCodebasePath();
+        if (globalCodebasePath)
+          codebaseRoot = path.resolve(globalCodebasePath);
+        else if (manifest.codebase_path)
+          codebaseRoot = path.resolve(projectRoot, manifest.codebase_path);
+        else {
+          const farmCodebaseRoot = await Model.resolveFarmCodebaseRoot(projectRoot);
+          farmCodebaseRoot && (codebaseRoot = farmCodebaseRoot);
+        }
+      }
+      const model = new Model(projectRoot, manifest, { ...options, codebaseRoot });
       if (!options.lazyLoad)
         try {
           if (manifestYaml.layers)
@@ -458,29 +647,37 @@ Run "dr init" to create a model.`);
       try {
         const activeId = (await fs.readFile(activePath, "utf-8")).trim();
         if (activeId) {
-          model._activeChangesetId = activeId;
-          const changeset = await new StagedChangesetStorage(projectRoot).load(activeId);
-          if (changeset)
-            for (const change of changeset.changes) {
-              if ((change.type === "add" || change.type === "update" || change.type === "delete") && model._stagedLayerNames.add(change.layerName), change.type === "relationship-add" && change.after) {
-                const rel = change.after;
-                model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
-                  source: rel.source,
-                  target: rel.target,
-                  predicate: rel.predicate,
-                  layer: rel.layer,
-                  ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
-                  category: rel.category ?? "structural",
-                  ...rel.properties ? { properties: rel.properties } : {}
-                });
-              }
-              if (change.type === "relationship-delete" && change.before) {
-                const rel = change.before;
-                model.relationships.delete(rel.source, rel.target, rel.predicate);
+          model._activeChangesetId = activeId, model._baseRelationships = model.relationships.getAll();
+          const storage = new StagedChangesetStorage(projectRoot);
+          try {
+            const changeset = await storage.load(activeId);
+            if (changeset)
+              for (const change of changeset.changes) {
+                if ((change.type === "add" || change.type === "update" || change.type === "delete") && model._stagedLayerNames.add(change.layerName), change.type === "relationship-add" && change.after) {
+                  const rel = change.after;
+                  model.relationships.find(rel.source, rel.target, rel.predicate).length === 0 && model.relationships.add({
+                    source: rel.source,
+                    target: rel.target,
+                    predicate: rel.predicate,
+                    layer: rel.layer,
+                    ...rel.targetLayer ? { targetLayer: rel.targetLayer } : {},
+                    category: rel.category ?? "structural",
+                    ...rel.properties ? { properties: rel.properties } : {}
+                  });
+                }
+                if (change.type === "relationship-delete" && change.before) {
+                  const rel = change.before;
+                  model.relationships.delete(rel.source, rel.target, rel.predicate);
+                }
               }
-            }
+          } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to load active changeset '${activeId}': ${errorMessage}`, { cause: err });
+          }
         }
-      } catch {
+      } catch (err) {
+        if (!(err?.code === "ENOENT"))
+          throw err;
         model._activeChangesetId = null;
       }
       let entityCount = 0;
@@ -496,13 +693,28 @@ Run "dr init" to create a model.`);
    * Initialize a new model in a directory
    */
   static async init(rootPath, manifestData, options = {}) {
+    const yaml = await import("yaml");
     await ensureDir(`${rootPath}/documentation-robotics/model`);
     for (let i = 0; i < CANONICAL_LAYER_NAMES.length; i++) {
       const orderNum = String(i + 1).padStart(2, "0"), layerName = CANONICAL_LAYER_NAMES[i];
       await ensureDir(`${rootPath}/documentation-robotics/model/${orderNum}_${layerName}`);
     }
-    const manifest = new Manifest(manifestData), model = new Model(rootPath, manifest, options);
-    return await model.saveManifest(), model;
+    const manifest = new Manifest(manifestData);
+    let codebaseRoot = rootPath;
+    if (options.codebaseRoot)
+      codebaseRoot = options.codebaseRoot;
+    else {
+      const globalCodebasePath = getCodebasePath();
+      globalCodebasePath ? codebaseRoot = path.resolve(globalCodebasePath) : manifest.codebase_path && (codebaseRoot = path.resolve(rootPath, manifest.codebase_path));
+    }
+    const model = new Model(rootPath, manifest, { ...options, codebaseRoot });
+    await model.saveManifest();
+    const relationshipsPath = `${rootPath}/documentation-robotics/model/relationships.yaml`, yamlContent = `# Intra-layer relationships
+# Format: source_id -> predicate -> target_id
+# Last updated: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+` + yaml.stringify([]);
+    return await writeFile(relationshipsPath, yamlContent), model;
   }
   /**
    * Graph-based API methods for querying the model
@@ -592,6 +804,7 @@ Run "dr init" to create a model.`);
    * @throws Error if atomic write fails
    */
   async saveDirtyLayersAtomic() {
+    assertBaseModelWritable();
     const tempLayerWrites = [];
     try {
       for (const layer of this.layers.values())