Models: main.archify, registries, refs, links and the model page; 0.7.0

A folder with main.archify at its top is a model, a set of diagrams
that belong together. Opening main.archify shows the model page: the
model's name and description, its own overview diagram when the file
has one, the diagrams grouped by folder (click to open), and the
registry with where each element is used. The page is built by
traversing the folder tree and refreshes when files change.

*.archify-registry files define shared elements once; diagrams draw
them with `ref: <id>` plus position and may override label, sublabel
and tag. References are resolved before Archify runs, so Archify is
unchanged. Hover, go-to-definition and completion on ref; unknown
names, forbidden overrides, duplicate ids and broken registries in
Problems; registry edits re-render open diagrams. `diagram:` links on
elements and components open the linked diagram on double-click.

New command Archify | Open Model, a Model template for New Diagram…,
editor schemas for the new keys and for registries, docs/model.md and
examples/online-shop. Single diagrams behave exactly as before.

src/commands/context.ts

@@ -1,5 +1,6 @@
 import * as vscode from 'vscode';
 import { HTML_VIEW_TYPE, HtmlViewerProvider } from '../views/htmlViewer';
+import { ModelService } from '../model/service';
 import { DiagramViewManager } from '../views/diagramView';
 
 /** What command handlers share: the extension context and the open views. */
@@ -7,6 +8,7 @@ export interface CommandContext {
   extension: vscode.ExtensionContext;
   views: DiagramViewManager;
   htmlViewer: HtmlViewerProvider;
+  models: ModelService;
 }
 
 export function isHtmlUri(uri: vscode.Uri): boolean {

src/commands/contextKeys.ts

@@ -1,14 +1,16 @@
 import * as vscode from 'vscode';
 import { clearGitRootCache } from '../archify/runtime';
+import { ModelService } from '../model/service';
 import { isArchifyFile, isArchifyHtml, isDiagramFileName, readDiagramSource } from '../sources/detect';
 
 const JSON_LANGUAGES = new Set(['json', 'jsonc']);
 
 /** Keeps the archify.* context keys (editor title buttons, keybindings) up to date. */
-export function registerContextKeys(context: vscode.ExtensionContext): void {
+export function registerContextKeys(context: vscode.ExtensionContext, models: ModelService): void {
   let contextTimer: NodeJS.Timeout | undefined;
   const updateContext = () => {
     const doc = vscode.window.activeTextEditor?.document;
+    if (doc) void models.rootOf(doc.uri).then((root) => vscode.commands.executeCommand('setContext', 'archify.inModel', Boolean(root)));
     const diagram = Boolean(
       doc &&
         (isArchifyFile(doc.fileName) ||

src/commands/modelCommands.ts

@@ -0,0 +1,19 @@
+import * as vscode from 'vscode';
+import { MAIN_FILE } from '../model/format';
+import { DIAGRAM_EDITOR_VIEW_TYPE } from '../views/diagramView';
+import { CommandContext, targetUri } from './context';
+
+export function modelCommands(ctx: CommandContext): vscode.Disposable[] {
+  return [
+    // Opens the model page (main.archify) of the model the current file is in.
+    vscode.commands.registerCommand('archify.openModel', async (arg?: unknown) => {
+      const uri = targetUri(ctx, arg);
+      const root = uri ? await ctx.models.rootOf(uri) : undefined;
+      if (!root) {
+        vscode.window.showInformationMessage(`Archify: this file is not inside a model (no ${MAIN_FILE} in a folder above it).`);
+        return;
+      }
+      await vscode.commands.executeCommand('vscode.openWith', vscode.Uri.joinPath(root, MAIN_FILE), DIAGRAM_EDITOR_VIEW_TYPE, vscode.ViewColumn.Active);
+    }),
+  ];
+}

src/commands/newDiagram.ts

@@ -1,5 +1,6 @@
+import path from 'node:path';
 import * as vscode from 'vscode';
-import { diagramFromTemplate, diagramName, invalidNameReason, TEMPLATES } from '../language/templates';
+import { diagramFromTemplate, diagramName, invalidNameReason, modelFromTemplate, TEMPLATES } from '../language/templates';
 import { diagramBaseName, isArchifyFile } from '../sources/detect';
 import { readText } from '../util/files';
 import { DIAGRAM_EDITOR_VIEW_TYPE } from '../views/diagramView';
@@ -24,11 +25,17 @@ export function newDiagramCommands(ctx: CommandContext): vscode.Disposable[] {
         { title: 'Archify | New Diagram', placeHolder: 'Kind of diagram' },
       );
       if (!template) return;
-      const { file, defaultName } = template.template;
+      const { file, defaultName, fixedName } = template.template;
 
       const folder = await newDiagramFolder(arg);
       let target: vscode.Uri | undefined;
-      if (folder) {
+      if (folder && fixedName) {
+        target = vscode.Uri.joinPath(folder, fixedName);
+        if (await exists(target)) {
+          vscode.window.showWarningMessage(`Archify: ${vscode.workspace.asRelativePath(folder, true)} already has a ${fixedName}.`);
+          return;
+        }
+      } else if (folder) {
         const name = await vscode.window.showInputBox({
           title: 'Archify | New Diagram',
           prompt: `File name in ${vscode.workspace.asRelativePath(folder, true)}`,
@@ -51,7 +58,9 @@ export function newDiagramCommands(ctx: CommandContext): vscode.Disposable[] {
       }
 
       const templateText = await readText(vscode.Uri.joinPath(ctx.extension.extensionUri, 'templates', file));
-      const text = diagramFromTemplate(templateText, diagramBaseName(target.path));
+      const text = fixedName
+        ? modelFromTemplate(templateText, path.basename(path.dirname(target.fsPath)))
+        : diagramFromTemplate(templateText, diagramBaseName(target.path));
       await vscode.workspace.fs.writeFile(target, Buffer.from(text, 'utf8'));
       await vscode.commands.executeCommand('vscode.openWith', target, DIAGRAM_EDITOR_VIEW_TYPE);
     }),

src/commands/renderCommands.ts

@@ -3,7 +3,8 @@ import path from 'node:path';
 import * as vscode from 'vscode';
 import { isEvidenceError, renderDiagram, renderToFile } from '../archify/cli';
 import { evidenceMode, runtimeFor } from '../archify/runtime';
-import { diagramBaseName, readDiagramSource } from '../sources/detect';
+import { prepareDiagram } from '../model/prepare';
+import { diagramBaseName } from '../sources/detect';
 import { log } from '../util/log';
 import { readText } from '../util/files';
 import { CommandContext, isHtmlUri, openHtmlViewer, sourceUri } from './context';
@@ -14,7 +15,7 @@ export function renderCommands(ctx: CommandContext): vscode.Disposable[] {
       const uri = sourceUri(ctx, arg);
       if (!uri) return;
       const text = await readText(uri);
-      const source = readDiagramSource(text, uri.path);
+      const source = (await prepareDiagram(ctx.models, uri, text))?.source;
       if (!source) {
         vscode.window.showWarningMessage(`Archify: ${path.basename(uri.path)} has no "diagram_type" (architecture, workflow, sequence, dataflow or lifecycle).`);
         return;
@@ -66,7 +67,7 @@ export function renderCommands(ctx: CommandContext): vscode.Disposable[] {
         return;
       }
       const text = await readText(uri);
-      const source = readDiagramSource(text, uri.path);
+      const source = (await prepareDiagram(ctx.models, uri, text))?.source;
       if (!source) {
         vscode.window.showWarningMessage(`Archify: ${path.basename(uri.path)} has no "diagram_type" (architecture, workflow, sequence, dataflow or lifecycle).`);
         return;

src/extension.ts

@@ -4,29 +4,40 @@ import { registerContextKeys } from './commands/contextKeys';
 import { newDiagramCommands } from './commands/newDiagram';
 import { renderCommands } from './commands/renderCommands';
 import { viewCommands } from './commands/viewCommands';
+import { modelCommands } from './commands/modelCommands';
 import { BRAND_COMPLETION_SELECTOR, BrandCompletionProvider } from './language/brandCompletion';
+import { REF_SELECTOR, RefLanguage } from './language/refLanguage';
+import { ModelService } from './model/service';
 import { DiagnosticsController } from './language/diagnostics';
 import { log } from './util/log';
 import { HtmlViewerProvider } from './views/htmlViewer';
 import { DiagramViewManager } from './views/diagramView';
 
 export function activate(context: vscode.ExtensionContext): void {
+  const models = new ModelService();
   const ctx: CommandContext = {
     extension: context,
-    views: new DiagramViewManager(context),
+    views: new DiagramViewManager(context, models),
     htmlViewer: new HtmlViewerProvider(context.extensionUri),
+    models,
   };
+  const refs = new RefLanguage(models);
   context.subscriptions.push(
+    models,
     ctx.views,
     ctx.htmlViewer,
-    new DiagnosticsController(context),
+    new DiagnosticsController(context, models),
     log(),
     vscode.languages.registerCompletionItemProvider(BRAND_COMPLETION_SELECTOR, new BrandCompletionProvider(context.extensionPath), ' ', '"'),
+    vscode.languages.registerCompletionItemProvider(REF_SELECTOR, refs, ' ', '"'),
+    vscode.languages.registerHoverProvider(REF_SELECTOR, refs),
+    vscode.languages.registerDefinitionProvider(REF_SELECTOR, refs),
     ...viewCommands(ctx),
     ...newDiagramCommands(ctx),
     ...renderCommands(ctx),
+    ...modelCommands(ctx),
   );
-  registerContextKeys(context);
+  registerContextKeys(context, models);
 }
 
 export function deactivate(): void {}

src/language/diagnostics.ts

@@ -2,8 +2,12 @@ import { parse, ParseError } from 'jsonc-parser';
 import * as vscode from 'vscode';
 import { ArchifyDiagnostic, isEvidenceError, validate } from '../archify/cli';
 import { evidenceMode, runtimeFor } from '../archify/runtime';
-import { isArchifyFile, readDiagramSource } from '../sources/detect';
+import { ModelProblem, isRegistryFile, parseRegistry } from '../model/format';
+import { prepareDiagram } from '../model/prepare';
+import { ModelService } from '../model/service';
+import { isArchifyFile } from '../sources/detect';
 import { log } from '../util/log';
+import path from 'node:path';
 import { diagnosticPointer, rangeForPointer, rangeForPointerYaml, yamlSyntaxProblems } from './jsonPointer';
 
 const JSON_LANGUAGES = new Set(['json', 'jsonc']);
@@ -29,9 +33,13 @@ export class DiagnosticsController implements vscode.Disposable {
   private readonly sequence = new Map<string, number>();
   private readonly disposables: vscode.Disposable[];
 
-  constructor(private readonly context: vscode.ExtensionContext) {
+  constructor(
+    private readonly context: vscode.ExtensionContext,
+    private readonly models: ModelService,
+  ) {
     this.disposables = [
       this.collection,
+      models.onDidChangeModel(() => this.revalidateAll()),
       vscode.workspace.onDidOpenTextDocument((doc) => this.schedule(doc, 0)),
       vscode.workspace.onDidChangeTextDocument((event) => {
         if (event.contentChanges.length) this.schedule(event.document, 700);
@@ -62,7 +70,7 @@ export class DiagnosticsController implements vscode.Disposable {
   }
 
   private schedule(doc: vscode.TextDocument, delay: number): void {
-    if (!JSON_LANGUAGES.has(doc.languageId) && !isArchifyFile(doc.fileName)) return;
+    if (!JSON_LANGUAGES.has(doc.languageId) && !isArchifyFile(doc.fileName) && !isRegistryFile(doc.fileName)) return;
     const key = doc.uri.toString();
     clearTimeout(this.timers.get(key));
     this.timers.set(key, setTimeout(() => void this.validate(doc), delay));
@@ -79,6 +87,10 @@ export class DiagnosticsController implements vscode.Disposable {
       this.collection.delete(doc.uri);
       return;
     }
+    if (isRegistryFile(doc.fileName)) {
+      await this.validateRegistry(doc, seq);
+      return;
+    }
     if (isArchifyFile(doc.fileName)) {
       // Nothing else reports YAML syntax errors in .archify files, and a file
       // that does not parse has no diagram to validate yet.
@@ -99,11 +111,16 @@ export class DiagnosticsController implements vscode.Disposable {
         return;
       }
     }
-    const source = readDiagramSource(text, doc.fileName);
-    if (!source) {
+    const prepared = await prepareDiagram(this.models, doc.uri, text);
+    if (seq !== this.sequence.get(key) || doc.isClosed) return;
+    if (!prepared) {
       this.collection.delete(doc.uri);
       return;
     }
+    const source = prepared.source;
+    const modelDiagnostics = prepared.problems
+      .filter((problem) => !problem.file)
+      .map((problem) => this.modelDiagnostic(doc, text, source.format, problem));
     if (source.format === 'json') {
       // Leave JSON syntax errors to the JSON language service.
       const syntax: ParseError[] = [];
@@ -131,9 +148,9 @@ export class DiagnosticsController implements vscode.Disposable {
       }
 
       const downgradeEvidence = evidenceMode(doc.uri) === 'fallback';
-      this.collection.set(
-        doc.uri,
-        result.diagnostics.map((item) => {
+      this.collection.set(doc.uri, [
+        ...modelDiagnostics,
+        ...result.diagnostics.map((item) => {
           const pointer = diagnosticPointer(item);
           const offsets = source.format === 'yaml' ? rangeForPointerYaml(text, pointer) : rangeForPointer(text, pointer);
           const range = new vscode.Range(doc.positionAt(offsets.start), doc.positionAt(offsets.end));
@@ -147,12 +164,42 @@ export class DiagnosticsController implements vscode.Disposable {
           if (item.code) diagnostic.code = item.code;
           return diagnostic;
         }),
-      );
+      ]);
     } catch (error) {
       log().error(`Validation failed for ${doc.uri.fsPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
 
+  private modelDiagnostic(doc: vscode.TextDocument, text: string, format: 'yaml' | 'json', problem: ModelProblem): vscode.Diagnostic {
+    const offsets = format === 'yaml' ? rangeForPointerYaml(text, problem.pointer) : rangeForPointer(text, problem.pointer);
+    const range = problem.line !== undefined && !problem.pointer ? doc.lineAt(Math.min(problem.line, doc.lineCount - 1)).range : new vscode.Range(doc.positionAt(offsets.start), doc.positionAt(offsets.end));
+    const diagnostic = new vscode.Diagnostic(range, problem.message, problem.severity === 'warning' ? vscode.DiagnosticSeverity.Warning : vscode.DiagnosticSeverity.Error);
+    diagnostic.source = 'archify';
+    return diagnostic;
+  }
+
+  /** A registry file: its own YAML and element problems, plus duplicates across the model. */
+  private async validateRegistry(doc: vscode.TextDocument, seq: number): Promise<void> {
+    const text = doc.getText();
+    const root = await this.models.rootOf(doc.uri);
+    const rel = root ? path.relative(root.fsPath, doc.uri.fsPath) : path.basename(doc.uri.fsPath);
+    const problems: ModelProblem[] = [...parseRegistry(text, rel).problems];
+    if (root) {
+      try {
+        const index = await this.models.index(root);
+        for (const problem of index.registry.problems) {
+          if (problem.file === rel && !problems.some((p) => p.message === problem.message)) problems.push(problem);
+        }
+      } catch {
+        // The index reports its own failures when the model page opens.
+      }
+    } else {
+      problems.push({ message: `This registry is not inside a model: no main.archify above ${path.basename(doc.uri.fsPath)}.`, severity: 'warning', line: 0 });
+    }
+    if (seq !== this.sequence.get(doc.uri.toString()) || doc.isClosed) return;
+    this.collection.set(doc.uri, problems.map((problem) => this.modelDiagnostic(doc, text, 'yaml', problem)));
+  }
+
   dispose(): void {
     for (const timer of this.timers.values()) clearTimeout(timer);
     for (const disposable of this.disposables.splice(0)) disposable.dispose();

src/language/refLanguage.ts

@@ -0,0 +1,72 @@
+import * as vscode from 'vscode';
+import { RegistryElement } from '../model/format';
+import { ModelService } from '../model/service';
+
+export const REF_SELECTOR: vscode.DocumentSelector = [{ pattern: '**/*.archify' }];
+
+/** `ref: api` or `{ ref: ap` → what has been typed of the value. */
+export function refValueAt(linePrefix: string): { typed: string } | undefined {
+  const match = /(?:^|[\s{,])ref:\s*["']?([\w.-]*)$/.exec(linePrefix);
+  return match ? { typed: match[1] } : undefined;
+}
+
+/** The `ref` value under a position, with its range, or undefined. */
+export function refAt(line: string, character: number): { id: string; start: number; end: number } | undefined {
+  const match = /(?:^|[\s{,])ref:\s*["']?([\w.-]+)/.exec(line);
+  if (!match) return undefined;
+  const start = match.index + match[0].length - match[1].length;
+  const end = start + match[1].length;
+  return character >= start && character <= end ? { id: match[1], start, end } : undefined;
+}
+
+function describe(element: RegistryElement): vscode.MarkdownString {
+  const md = new vscode.MarkdownString();
+  md.appendMarkdown(`**${element.label ?? element.id}**${element.sublabel ? ` · ${element.sublabel}` : ''}${element.type ? ` \`${element.type}\`` : ''}\n\n`);
+  if (element.description) md.appendMarkdown(`${element.description.trim()}\n\n`);
+  if (element.diagram) md.appendMarkdown(`Opens: \`${element.diagram}\`\n\n`);
+  md.appendMarkdown(`*Defined in ${element.file}, line ${element.line + 1}*`);
+  return md;
+}
+
+/** Completion, hover and go-to-definition for `ref:` values in diagrams of a model. */
+export class RefLanguage implements vscode.CompletionItemProvider, vscode.HoverProvider, vscode.DefinitionProvider {
+  constructor(private readonly models: ModelService) {}
+
+  async provideCompletionItems(document: vscode.TextDocument, position: vscode.Position): Promise<vscode.CompletionItem[] | undefined> {
+    const value = refValueAt(document.lineAt(position.line).text.slice(0, position.character));
+    if (!value) return undefined;
+    const found = await this.models.registryFor(document.uri);
+    if (!found) return undefined;
+    const range = new vscode.Range(position.translate(0, -value.typed.length), position);
+    return [...found.registry.elements.values()].map((element) => {
+      const item = new vscode.CompletionItem({ label: element.id, description: element.label }, vscode.CompletionItemKind.Reference);
+      item.detail = [element.label, element.sublabel, element.type].filter(Boolean).join(' · ');
+      item.documentation = describe(element);
+      item.filterText = [element.id, element.label ?? '', element.sublabel ?? ''].join(' ');
+      item.range = range;
+      return item;
+    });
+  }
+
+  async provideHover(document: vscode.TextDocument, position: vscode.Position): Promise<vscode.Hover | undefined> {
+    const ref = refAt(document.lineAt(position.line).text, position.character);
+    if (!ref) return undefined;
+    const found = await this.models.registryFor(document.uri);
+    const element = found?.registry.elements.get(ref.id);
+    const range = new vscode.Range(position.line, ref.start, position.line, ref.end);
+    if (!element) {
+      return new vscode.Hover(found ? `Unknown element \`${ref.id}\`: no registry of this model defines it.` : `\`${ref.id}\` cannot be resolved: this file is not inside a model.`, range);
+    }
+    return new vscode.Hover(describe(element), range);
+  }
+
+  async provideDefinition(document: vscode.TextDocument, position: vscode.Position): Promise<vscode.Location | undefined> {
+    const ref = refAt(document.lineAt(position.line).text, position.character);
+    if (!ref) return undefined;
+    const found = await this.models.registryFor(document.uri);
+    const element = found?.registry.elements.get(ref.id);
+    if (!found || !element) return undefined;
+    const file = vscode.Uri.joinPath(found.root, ...element.file.split(/[\\/]/));
+    return new vscode.Location(file, new vscode.Position(element.line, 2));
+  }
+}

src/language/templates.ts

@@ -9,6 +9,8 @@ export interface DiagramTemplate {
   description: string;
   /** Suggested name for the new file, without .archify. */
   defaultName: string;
+  /** Reserved file name; the user is not asked for one. */
+  fixedName?: string;
 }
 
 export const TEMPLATES: readonly DiagramTemplate[] = [
@@ -18,6 +20,7 @@ export const TEMPLATES: readonly DiagramTemplate[] = [
   { file: 'dataflow.archify', type: 'dataflow', label: 'Data Flow', description: 'Where data comes from and where it goes', defaultName: 'dataflow' },
   { file: 'lifecycle.archify', type: 'lifecycle', label: 'Lifecycle', description: 'States something moves through', defaultName: 'lifecycle' },
   { file: 'everyday-plan.archify', type: 'workflow', label: 'Everyday Plan', description: 'A plan or process from daily life', defaultName: 'plan' },
+  { file: 'model.archify', type: 'architecture', label: 'Model (main.archify)', description: 'Entry point of a folder of diagrams that belong together', defaultName: 'main', fixedName: 'main.archify' },
 ];
 
 /** Strips a typed .archify suffix and surrounding spaces. */
@@ -40,6 +43,21 @@ export function titleFromName(name: string): string {
   return words ? words.charAt(0).toUpperCase() + words.slice(1) : name;
 }
 
+/** "online-shop" → "online-shop"; "My Shop 2" → "my-shop-2": a model id from a folder name. */
+export function modelIdFromName(name: string): string {
+  const id = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return /^[a-z]/.test(id) ? id : `m-${id || 'model'}`;
+}
+
+/** The model template with id, name and overview title taken from the folder name. */
+export function modelFromTemplate(templateText: string, folderName: string): string {
+  const doc = parseDocument(templateText);
+  doc.setIn(['model', 'id'], modelIdFromName(folderName));
+  doc.setIn(['model', 'name'], titleFromName(folderName));
+  doc.setIn(['meta', 'title'], `${titleFromName(folderName)} overview`);
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}
+
 /**
  * Template YAML with meta.title and meta.output set for the new file.
  * Works on the YAML document so the template's comments and layout stay.

src/model/format.ts

@@ -0,0 +1,272 @@
+import { isMap, isScalar, parseDocument, parse as parseYaml } from 'yaml';
+
+/**
+ * The model file formats (see docs/model.md): `main.archify` with a `model`
+ * block, `*.archify-registry` files with shared elements, and `ref`
+ * components in diagrams. Pure functions, no VS Code imports, so they run
+ * in unit tests and can be reused by other tools.
+ */
+
+export const MAIN_FILE = 'main.archify';
+export const REGISTRY_EXT = '.archify-registry';
+
+/** Component fields copied from a registry element into every diagram that refers to it. */
+export const COPIED_FIELDS = ['type', 'label', 'sublabel', 'tag', 'icon', 'brand', 'sources'] as const;
+/** The subset a diagram may override on a `ref` component. */
+export const OVERRIDABLE_FIELDS = ['label', 'sublabel', 'tag'] as const;
+
+export interface ModelMeta {
+  id?: string;
+  name?: string;
+  description?: string;
+}
+
+export interface RegistryElement {
+  id: string;
+  type?: string;
+  label?: string;
+  sublabel?: string;
+  tag?: string;
+  icon?: unknown;
+  brand?: string;
+  sources?: unknown;
+  description?: string;
+  /** Diagram that explains the element, relative to the model root. */
+  diagram?: string;
+  /** Registry file that defines it, and the 0-based line of its key. */
+  file: string;
+  line: number;
+}
+
+export interface ModelProblem {
+  message: string;
+  severity: 'error' | 'warning';
+  /** File the problem is about; defaults to the diagram being resolved. */
+  file?: string;
+  /** JSON pointer into that file's document, when it is a diagram. */
+  pointer?: string;
+  /** 0-based line, when known (registry files). */
+  line?: number;
+}
+
+export interface Registry {
+  elements: Map<string, RegistryElement>;
+  files: string[];
+  problems: ModelProblem[];
+}
+
+export function isMainFile(fileName: string): boolean {
+  return (fileName.split(/[\\/]/).pop() ?? '') === MAIN_FILE;
+}
+
+export function isRegistryFile(fileName: string): boolean {
+  return fileName.endsWith(REGISTRY_EXT);
+}
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => v !== null && typeof v === 'object' && !Array.isArray(v);
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v.length > 0 ? v : undefined);
+
+/** The `model` block of a `main.archify` document, if present. */
+export function readModelMeta(doc: unknown): ModelMeta | undefined {
+  if (!isObj(doc) || !isObj(doc.model)) return undefined;
+  const { id, name, description } = doc.model;
+  return { id: str(id), name: str(name), description: str(description) };
+}
+
+/** True when the document also carries a diagram (a `diagram_type`). */
+export function hasDiagramBody(doc: unknown): boolean {
+  return isObj(doc) && typeof doc.diagram_type === 'string';
+}
+
+/** Parses one registry file. Line numbers come from the YAML document. */
+export function parseRegistry(text: string, file: string): { elements: RegistryElement[]; problems: ModelProblem[] } {
+  const problems: ModelProblem[] = [];
+  const elements: RegistryElement[] = [];
+  const doc = parseDocument(text, { prettyErrors: false, uniqueKeys: false });
+  for (const error of doc.errors) {
+    problems.push({ message: `Registry is not valid YAML: ${error.message.split('\n')[0]}`, severity: 'error', file, line: error.linePos?.[0].line ? error.linePos[0].line - 1 : 0 });
+  }
+  if (doc.errors.length) return { elements, problems };
+  const lineOf = (offset: number | undefined) => (offset === undefined ? 0 : text.slice(0, offset).split('\n').length - 1);
+  const root = doc.contents;
+  if (!isMap(root)) {
+    problems.push({ message: 'A registry must be a mapping with an "elements" key.', severity: 'error', file, line: 0 });
+    return { elements, problems };
+  }
+  const elementsNode = root.get('elements', true);
+  if (!isMap(elementsNode)) {
+    problems.push({ message: 'A registry needs an "elements" mapping (id → element).', severity: 'error', file, line: 0 });
+    return { elements, problems };
+  }
+  for (const pair of elementsNode.items) {
+    const key = pair.key;
+    const id = isScalar(key) ? String(key.value) : undefined;
+    const line = isScalar(key) ? lineOf(key.range?.[0]) : 0;
+    if (!id) continue;
+    const value = isMap(pair.value) ? (pair.value.toJSON() as Obj) : undefined;
+    if (!value) {
+      problems.push({ message: `Element "${id}" must be a mapping (type, label, description, …).`, severity: 'error', file, line });
+      continue;
+    }
+    elements.push({
+      id,
+      type: str(value.type),
+      label: str(value.label),
+      sublabel: str(value.sublabel),
+      tag: str(value.tag),
+      icon: value.icon,
+      brand: str(value.brand),
+      sources: value.sources,
+      description: str(value.description),
+      diagram: str(value.diagram),
+      file,
+      line,
+    });
+  }
+  return { elements, problems };
+}
+
+/** Merges parsed registry files; an id defined twice is an error on the second definition. */
+export function mergeRegistries(parts: { elements: RegistryElement[]; problems: ModelProblem[]; file: string }[]): Registry {
+  const elements = new Map<string, RegistryElement>();
+  const problems: ModelProblem[] = [];
+  for (const part of parts) {
+    problems.push(...part.problems);
+    for (const element of part.elements) {
+      const existing = elements.get(element.id);
+      if (existing) {
+        problems.push({
+          message: `Element "${element.id}" is defined twice (also in ${existing.file}, line ${existing.line + 1}).`,
+          severity: 'error',
+          file: element.file,
+          line: element.line,
+        });
+        continue;
+      }
+      elements.set(element.id, element);
+    }
+  }
+  return { elements, files: parts.map((p) => p.file), problems };
+}
+
+export interface ResolvedDiagram {
+  /** The diagram as Archify expects it: refs expanded, model block and links removed. */
+  diagram: Obj;
+  problems: ModelProblem[];
+  /** Component index → the registry element it came from. */
+  refs: Map<number, RegistryElement>;
+  /** Node id → diagram path (relative to the model root) it links to. */
+  links: Map<string, string>;
+  /** Registry element ids used by this diagram. */
+  used: Set<string>;
+}
+
+export interface ResolveOptions {
+  /** Undefined when the diagram is not inside a model. */
+  registry?: Registry;
+  fileName: string;
+}
+
+/**
+ * Expands `ref` components from the registry and strips what Archify does
+ * not know. Component order and indexes are kept, so Archify's diagnostics
+ * (JSON pointers) still point at the right component in the source file.
+ */
+export function resolveRefs(doc: unknown, options: ResolveOptions): ResolvedDiagram {
+  const problems: ModelProblem[] = [];
+  const refs = new Map<number, RegistryElement>();
+  const links = new Map<string, string>();
+  const used = new Set<string>();
+  if (!isObj(doc)) return { diagram: {}, problems, refs, links, used };
+  const diagram: Obj = { ...doc };
+  delete diagram.model;
+  const { registry } = options;
+  const components = Array.isArray(doc.components) ? doc.components : undefined;
+  if (!components) return { diagram, problems, refs, links, used };
+
+  diagram.components = components.map((raw, index) => {
+    if (!isObj(raw)) return raw;
+    const ref = str(raw.ref);
+    const linkFromComponent = str(raw.diagram);
+    if (!ref) {
+      const { diagram: _link, ...plain } = raw;
+      const id = str(plain.id);
+      if (id && linkFromComponent) links.set(id, linkFromComponent);
+      return plain;
+    }
+    const { ref: _ref, diagram: _link, ...own } = raw;
+    const element = registry?.elements.get(ref);
+    const id = str(own.id) ?? ref;
+    if (!element) {
+      problems.push({
+        message: registry
+          ? `Unknown element "${ref}": no registry of this model defines it.`
+          : `"${ref}" cannot be resolved: ${options.fileName.split(/[\\/]/).pop()} is not inside a model (no ${MAIN_FILE} above it).`,
+        severity: 'error',
+        pointer: `/components/${index}/ref`,
+      });
+      return { type: 'external', label: ref, ...own, id };
+    }
+    used.add(ref);
+    refs.set(index, element);
+    for (const key of Object.keys(own)) {
+      if ((COPIED_FIELDS as readonly string[]).includes(key) && !(OVERRIDABLE_FIELDS as readonly string[]).includes(key)) {
+        problems.push({
+          message: `"${key}" comes from the registry element "${ref}" and cannot be changed in a diagram.`,
+          severity: 'error',
+          pointer: `/components/${index}/${key}`,
+        });
+      }
+    }
+    const merged: Obj = { id };
+    for (const key of COPIED_FIELDS) if (element[key] !== undefined) merged[key] = element[key];
+    for (const [key, value] of Object.entries(own)) {
+      if (key === 'id') continue;
+      if (!(COPIED_FIELDS as readonly string[]).includes(key) || (OVERRIDABLE_FIELDS as readonly string[]).includes(key)) merged[key] = value;
+    }
+    const link = linkFromComponent ?? element.diagram;
+    if (link) links.set(id, link);
+    return merged;
+  });
+  return { diagram, problems, refs, links, used };
+}
+
+/** Group of a diagram inside a model: '' for the root folder, else the folder path with '/' separators. */
+export function groupOf(relativePath: string): string {
+  const parts = relativePath.split(/[\\/]/);
+  parts.pop();
+  return parts.join('/');
+}
+
+export interface DiagramSummary {
+  relativePath: string;
+  group: string;
+  kind?: string;
+  title?: string;
+  used: string[];
+  parseError?: string;
+}
+
+/** What the model page needs to know about one diagram file. */
+export function summarizeDiagram(text: string, relativePath: string): DiagramSummary {
+  let doc: unknown;
+  try {
+    doc = parseYaml(text, { prettyErrors: false, uniqueKeys: false });
+  } catch (error) {
+    return { relativePath, group: groupOf(relativePath), used: [], parseError: error instanceof Error ? error.message.split('\n')[0] : String(error) };
+  }
+  const obj = isObj(doc) ? doc : {};
+  const meta = isObj(obj.meta) ? obj.meta : {};
+  const components = Array.isArray(obj.components) ? obj.components : [];
+  const used = [...new Set(components.map((c) => (isObj(c) ? str(c.ref) : undefined)).filter((r): r is string => !!r))];
+  return { relativePath, group: groupOf(relativePath), kind: str(obj.diagram_type), title: str(meta.title), used };
+}
+
+/** Groups in display order: the root group first, then folders in path order. */
+export function sortedGroups(summaries: DiagramSummary[]): { group: string; diagrams: DiagramSummary[] }[] {
+  const byGroup = new Map<string, DiagramSummary[]>();
+  for (const s of summaries) byGroup.set(s.group, [...(byGroup.get(s.group) ?? []), s]);
+  const groups = [...byGroup.keys()].sort((a, b) => (a === '' ? -1 : b === '' ? 1 : a.localeCompare(b)));
+  return groups.map((group) => ({ group, diagrams: byGroup.get(group)!.sort((a, b) => a.relativePath.localeCompare(b.relativePath)) }));
+}

src/model/panel.ts

@@ -0,0 +1,29 @@
+import { ModelIndex } from './service';
+
+/** What the model page shows; serialised into the webview. */
+export interface ModelPanel {
+  meta: { id?: string; name?: string; description?: string };
+  /** True when main.archify also carries a diagram, shown between metadata and the list. */
+  hasDiagram: boolean;
+  groups: { group: string; diagrams: { path: string; title?: string; kind?: string; parseError?: string }[] }[];
+  registry: { id: string; label?: string; type?: string; description?: string; file: string; usedIn: string[] }[];
+  problems: string[];
+  nested: string[];
+}
+
+export function panelFromIndex(index: ModelIndex): ModelPanel {
+  const registry = [...index.registry.elements.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((e) => ({ id: e.id, label: e.label, type: e.type, description: e.description, file: e.file, usedIn: index.usage.get(e.id) ?? [] }));
+  return {
+    meta: index.meta,
+    hasDiagram: index.mainHasDiagram,
+    groups: index.groups.map((g) => ({
+      group: g.group,
+      diagrams: g.diagrams.map((d) => ({ path: d.relativePath, title: d.title, kind: d.kind, parseError: d.parseError })),
+    })),
+    registry,
+    problems: index.registry.problems.map((p) => (p.file ? `${p.file}: ${p.message}` : p.message)),
+    nested: index.nested,
+  };
+}

src/model/prepare.ts

@@ -0,0 +1,37 @@
+import * as vscode from 'vscode';
+import { DiagramSource, readDiagramSource } from '../sources/detect';
+import { ModelProblem, Registry, resolveRefs } from './format';
+import { ModelService } from './service';
+
+/**
+ * A diagram ready for Archify: the source as written, plus the resolved JSON
+ * with registry references expanded, the model problems found on the way,
+ * and the diagram links the viewer should offer.
+ */
+export interface PreparedDiagram {
+  source: DiagramSource;
+  /** Model root when the file is inside a model. */
+  root?: vscode.Uri;
+  registry?: Registry;
+  problems: ModelProblem[];
+  /** Node id → diagram path relative to the model root. */
+  links: Map<string, string>;
+}
+
+/**
+ * Reads a diagram and resolves it against its model, if any. Every place
+ * that hands a diagram to Archify (preview, Problems, render, browser) goes
+ * through here, so they all see the same resolved diagram.
+ */
+export async function prepareDiagram(models: ModelService, uri: vscode.Uri, text: string): Promise<PreparedDiagram | undefined> {
+  const source = readDiagramSource(text, uri.path);
+  if (!source) return undefined;
+  const found = await models.registryFor(uri);
+  const resolved = resolveRefs(source.diagram, { registry: found?.registry, fileName: uri.path });
+  // Only diagrams that use refs (or carry a model block) need the resolved form.
+  const changed = resolved.refs.size > 0 || resolved.problems.length > 0 || 'model' in source.diagram || resolved.links.size > 0;
+  const prepared: DiagramSource = changed
+    ? { ...source, diagram: resolved.diagram, json: JSON.stringify(resolved.diagram, null, 2) }
+    : source;
+  return { source: prepared, root: found?.root, registry: found?.registry, problems: resolved.problems, links: resolved.links };
+}

src/model/service.ts

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import * as vscode from 'vscode';
+import { log } from '../util/log';
+import {
+  DiagramSummary,
+  MAIN_FILE,
+  ModelMeta,
+  REGISTRY_EXT,
+  Registry,
+  hasDiagramBody,
+  isMainFile,
+  isRegistryFile,
+  mergeRegistries,
+  parseRegistry,
+  readModelMeta,
+  sortedGroups,
+  summarizeDiagram,
+} from './format';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * Finds models in the workspace and keeps what they contain. A model is the
+ * folder tree under a `main.archify`; this service answers "which model is
+ * this file in?", loads the model's registry, lists its diagrams, and tells
+ * listeners when any of that changes.
+ */
+
+export interface ModelIndex {
+  root: vscode.Uri;
+  main: vscode.Uri;
+  meta: ModelMeta;
+  /** True when main.archify also carries a diagram. */
+  mainHasDiagram: boolean;
+  registry: Registry;
+  diagrams: DiagramSummary[];
+  groups: { group: string; diagrams: DiagramSummary[] }[];
+  /** Element id → diagrams (relative paths) that refer to it. */
+  usage: Map<string, string[]>;
+  /** Nested main.archify files found below the root; not supported. */
+  nested: string[];
+}
+
+const SKIP = '{**/node_modules/**,**/.git/**}';
+
+async function exists(uri: vscode.Uri): Promise<boolean> {
+  try {
+    await vscode.workspace.fs.stat(uri);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function text(bytes: Uint8Array): string {
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+/** Open editor text when the file is open, else the file on disk. */
+async function readText(uri: vscode.Uri): Promise<string> {
+  const open = vscode.workspace.textDocuments.find((doc) => doc.uri.toString() === uri.toString());
+  if (open) return open.getText();
+  return text(await vscode.workspace.fs.readFile(uri));
+}
+
+export class ModelService implements vscode.Disposable {
+  private readonly roots = new Map<string, vscode.Uri | null>();
+  private readonly indexes = new Map<string, Promise<ModelIndex>>();
+  private readonly changeEmitter = new vscode.EventEmitter<{ root: vscode.Uri; file: vscode.Uri }>();
+  /** Fires with the model root and the file under it that changed. */
+  readonly onDidChangeModel = this.changeEmitter.event;
+  private readonly disposables: vscode.Disposable[];
+
+  constructor() {
+    const watcher = vscode.workspace.createFileSystemWatcher(`**/*{.archify,${REGISTRY_EXT}}`);
+    const changed = (uri: vscode.Uri) => void this.onFileChanged(uri);
+    this.disposables = [
+      watcher,
+      watcher.onDidCreate(changed),
+      watcher.onDidDelete(changed),
+      watcher.onDidChange(changed),
+      vscode.workspace.onDidChangeTextDocument((event) => {
+        // Registry edits in the editor should re-render open diagrams before a save.
+        if (isRegistryFile(event.document.fileName) || isMainFile(event.document.fileName)) changed(event.document.uri);
+      }),
+      this.changeEmitter,
+    ];
+  }
+
+  private async onFileChanged(uri: vscode.Uri): Promise<void> {
+    const name = path.basename(uri.path);
+    if (name === MAIN_FILE) this.roots.clear(); // a model may have appeared or disappeared
+    const root = await this.rootOf(uri);
+    if (!root) return;
+    this.indexes.delete(root.toString());
+    this.changeEmitter.fire({ root, file: uri });
+  }
+
+  /** The model root (folder with main.archify) above a file, or undefined. */
+  async rootOf(uri: vscode.Uri): Promise<vscode.Uri | undefined> {
+    if (uri.scheme !== 'file') return undefined;
+    const dirKey = path.dirname(uri.fsPath);
+    const cached = this.roots.get(dirKey);
+    if (cached !== undefined) return cached ?? undefined;
+    let dir = dirKey;
+    const visited: string[] = [];
+    let found: vscode.Uri | null = null;
+    for (;;) {
+      visited.push(dir);
+      if (await exists(vscode.Uri.file(path.join(dir, MAIN_FILE)))) {
+        found = vscode.Uri.file(dir);
+        break;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    for (const d of visited) this.roots.set(d, found);
+    return found ?? undefined;
+  }
+
+  /** The registry of the model a file belongs to, or undefined outside a model. */
+  async registryFor(uri: vscode.Uri): Promise<{ root: vscode.Uri; registry: Registry } | undefined> {
+    const root = await this.rootOf(uri);
+    if (!root) return undefined;
+    const index = await this.index(root);
+    return { root, registry: index.registry };
+  }
+
+  /** Everything known about a model, cached until a file under it changes. */
+  index(root: vscode.Uri): Promise<ModelIndex> {
+    const key = root.toString();
+    let pending = this.indexes.get(key);
+    if (!pending) {
+      pending = this.build(root).catch((error) => {
+        this.indexes.delete(key);
+        throw error;
+      });
+      this.indexes.set(key, pending);
+    }
+    return pending;
+  }
+
+  private async build(root: vscode.Uri): Promise<ModelIndex> {
+    const main = vscode.Uri.joinPath(root, MAIN_FILE);
+    let meta: ModelMeta = {};
+    let mainHasDiagram = false;
+    try {
+      const doc = parseYaml(await readText(main), { prettyErrors: false, uniqueKeys: false });
+      meta = readModelMeta(doc) ?? {};
+      mainHasDiagram = hasDiagramBody(doc);
+    } catch (error) {
+      log().warn(`main.archify of ${root.fsPath} does not parse: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    const registryFiles = await vscode.workspace.findFiles(new vscode.RelativePattern(root, `**/*${REGISTRY_EXT}`), SKIP);
+    const parts = await Promise.all(
+      registryFiles.sort((a, b) => a.fsPath.localeCompare(b.fsPath)).map(async (file) => {
+        const rel = path.relative(root.fsPath, file.fsPath);
+        return { file: rel, ...parseRegistry(await readText(file), rel) };
+      }),
+    );
+    const registry = mergeRegistries(parts);
+
+    const diagramFiles = await vscode.workspace.findFiles(new vscode.RelativePattern(root, '**/*.archify'), SKIP);
+    const nested: string[] = [];
+    const diagrams: DiagramSummary[] = [];
+    for (const file of diagramFiles) {
+      const rel = path.relative(root.fsPath, file.fsPath).split(path.sep).join('/');
+      if (rel === MAIN_FILE) continue;
+      if (path.basename(file.fsPath) === MAIN_FILE) {
+        nested.push(rel);
+        continue;
+      }
+      diagrams.push(summarizeDiagram(await readText(file), rel));
+    }
+    const usage = new Map<string, string[]>();
+    for (const d of diagrams) for (const id of d.used) usage.set(id, [...(usage.get(id) ?? []), d.relativePath]);
+    return { root, main, meta, mainHasDiagram, registry, diagrams, groups: sortedGroups(diagrams), usage, nested };
+  }
+
+  dispose(): void {
+    for (const d of this.disposables.splice(0)) d.dispose();
+  }
+}

src/views/diagramView.ts

@@ -2,12 +2,16 @@ import path from 'node:path';
 import * as vscode from 'vscode';
 import { renderDiagram } from '../archify/cli';
 import { evidenceMode, runtimeFor } from '../archify/runtime';
-import { isArchifyFile, readDiagramSource } from '../sources/detect';
+import { isMainFile, isRegistryFile } from '../model/format';
+import { ModelPanel, panelFromIndex } from '../model/panel';
+import { prepareDiagram } from '../model/prepare';
+import { ModelService } from '../model/service';
+import { isArchifyFile } from '../sources/detect';
 import { readText } from '../util/files';
 import { log } from '../util/log';
 import { viewerTheme } from '../util/settings';
 import { handleWebviewMessage, WebviewMessage } from '../webview/messages';
-import { makeNonce, messagePage, prepareDiagramHtml } from '../webview/page';
+import { makeNonce, messagePage, modelPage, prepareDiagramHtml } from '../webview/page';
 import { viewer3dOption, viewerRoots } from '../webview/viewer3d';
 
 export const PREVIEW_VIEW_TYPE = 'archify.preview';
@@ -28,9 +32,12 @@ class DiagramPreview implements vscode.Disposable {
   private readonly disposables: vscode.Disposable[] = [];
   private readonly onDisposeEmitter = new vscode.EventEmitter<void>();
   readonly onDidDispose = this.onDisposeEmitter.event;
+  /** Root of the model this file belongs to, once known. */
+  root: vscode.Uri | undefined;
 
   constructor(
     private readonly context: vscode.ExtensionContext,
+    private readonly models: ModelService,
     readonly panel: vscode.WebviewPanel,
     readonly uri: vscode.Uri,
     state?: PreviewState,
@@ -51,6 +58,10 @@ class DiagramPreview implements vscode.Disposable {
           this.hash = message.hash;
           return;
         }
+        if (message.type === 'openDiagram') {
+          void this.openLinked(message.path);
+          return;
+        }
         void handleWebviewMessage(message, this.uri, this.panel);
       }),
     );
@@ -84,6 +95,27 @@ class DiagramPreview implements vscode.Disposable {
     );
   }
 
+  /** Opens a diagram of the model, given its path relative to the model root. */
+  private async openLinked(relativePath: string): Promise<void> {
+    if (!this.root) return;
+    const target = vscode.Uri.joinPath(this.root, ...relativePath.split('/'));
+    try {
+      await vscode.workspace.fs.stat(target);
+    } catch {
+      vscode.window.showWarningMessage(`Archify: ${relativePath} does not exist in this model.`);
+      return;
+    }
+    await vscode.commands.executeCommand('vscode.openWith', target, DIAGRAM_EDITOR_VIEW_TYPE, vscode.ViewColumn.Active);
+  }
+
+  private showModelPage(model: ModelPanel): void {
+    const fingerprint = `model\u0000${JSON.stringify(model)}`;
+    if (fingerprint === this.lastHtml) return;
+    this.lastHtml = fingerprint;
+    this.rendered = false;
+    this.panel.webview.html = modelPage({ cspSource: this.panel.webview.cspSource, nonce: makeNonce(), state: this.state() }, model);
+  }
+
   scheduleUpdate(): void {
     const delay = vscode.workspace.getConfiguration('archify', this.uri).get<number>('preview.debounceMs', 400);
     clearTimeout(this.timer);
@@ -100,14 +132,37 @@ class DiagramPreview implements vscode.Disposable {
       this.showMessage('Cannot read diagram', this.uri.fsPath, error instanceof Error ? error.message : String(error));
       return;
     }
-    const source = readDiagramSource(text, this.uri.path);
-    if (!source) {
+    // main.archify: the model page wraps the diagram, or stands alone.
+    const main = isMainFile(this.uri.path) && this.uri.scheme === 'file';
+    let model: ModelPanel | undefined;
+    if (main) {
+      this.root = vscode.Uri.file(path.dirname(this.uri.fsPath));
+      try {
+        model = panelFromIndex(await this.models.index(this.root));
+      } catch (error) {
+        log().warn(`Model index failed for ${this.root.fsPath}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    let prepared;
+    try {
+      prepared = await prepareDiagram(this.models, this.uri, text);
+    } catch (error) {
+      log().warn(`Could not resolve ${this.uri.fsPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (seq !== this.seq) return;
+    if (!main) this.root = prepared?.root;
+    if (!prepared) {
+      if (model) {
+        this.showModelPage(model);
+        return;
+      }
       this.showMessage(
         'Nothing to show yet',
         `Set "diagram_type" to architecture, workflow, sequence, dataflow or lifecycle, and make sure the file is valid ${isArchifyFile(this.uri.path) ? 'YAML' : 'JSON'}.`,
       );
       return;
     }
+    const source = prepared.source;
 
     let result;
     try {
@@ -139,9 +194,11 @@ class DiagramPreview implements vscode.Disposable {
       state: this.state(),
       notice: result.evidenceNotice ? { kind: 'warning', text: result.evidenceNotice } : undefined,
       viewer3d: viewer3dOption(this.panel.webview, this.context.extensionUri),
+      links: Object.fromEntries(prepared.links),
+      model,
     });
     // Nonces differ per render, so compare the renderer output instead.
-    const fingerprint = `${viewerTheme()}\u0000${result.evidenceNotice ?? ''}\u0000${result.html}`;
+    const fingerprint = `${viewerTheme()}\u0000${result.evidenceNotice ?? ''}\u0000${JSON.stringify([model ?? null, [...prepared.links]])}\u0000${result.html}`;
     if (!force && this.rendered && fingerprint === this.lastHtml) {
       void this.panel.webview.postMessage({ type: 'notice', notice: undefined });
       return;
@@ -173,8 +230,20 @@ export class DiagramViewManager
   private active: DiagramPreview | undefined;
   private readonly disposables: vscode.Disposable[] = [];
 
-  constructor(private readonly context: vscode.ExtensionContext) {
+  constructor(
+    private readonly context: vscode.ExtensionContext,
+    private readonly models: ModelService,
+  ) {
     this.disposables.push(
+      // A registry or main.archify change re-renders every diagram of the model;
+      // any other file change only refreshes the model page's list.
+      models.onDidChangeModel(({ root, file }) => {
+        const whole = isRegistryFile(file.path) || isMainFile(file.path);
+        for (const preview of [...this.previews.values(), ...this.editors]) {
+          if (preview.root?.toString() !== root.toString()) continue;
+          if (whole || isMainFile(preview.uri.path)) preview.scheduleUpdate();
+        }
+      }),
       vscode.window.registerWebviewPanelSerializer(PREVIEW_VIEW_TYPE, this),
       vscode.window.registerCustomEditorProvider(DIAGRAM_EDITOR_VIEW_TYPE, this, {
         webviewOptions: { retainContextWhenHidden: true, enableFindWidget: true },
@@ -210,7 +279,7 @@ export class DiagramViewManager
   /** Opening a .archify file lands here: the diagram is the editor. */
   async resolveCustomTextEditor(document: vscode.TextDocument, panel: vscode.WebviewPanel): Promise<void> {
     panel.webview.options = { enableScripts: true, localResourceRoots: viewerRoots(this.context.extensionUri) };
-    this.track(new DiagramPreview(this.context, panel, document.uri, undefined, true));
+    this.track(new DiagramPreview(this.context, this.models, panel, document.uri, undefined, true));
   }
 
   show(uri: vscode.Uri, viewColumn: vscode.ViewColumn, preserveFocus = false): void {
@@ -225,7 +294,7 @@ export class DiagramViewManager
       { viewColumn, preserveFocus },
       { enableScripts: true, retainContextWhenHidden: true, enableFindWidget: true, localResourceRoots: viewerRoots(this.context.extensionUri) },
     );
-    this.track(new DiagramPreview(this.context, panel, uri));
+    this.track(new DiagramPreview(this.context, this.models, panel, uri));
   }
 
   async deserializeWebviewPanel(panel: vscode.WebviewPanel, state: PreviewState | undefined): Promise<void> {
@@ -233,7 +302,7 @@ export class DiagramViewManager
       panel.dispose();
       return;
     }
-    this.track(new DiagramPreview(this.context, panel, vscode.Uri.parse(state.uri), state));
+    this.track(new DiagramPreview(this.context, this.models, panel, vscode.Uri.parse(state.uri), state));
   }
 
   private track(preview: DiagramPreview): void {
@@ -247,6 +316,7 @@ export class DiagramViewManager
       if (preview.panel.active) this.active = preview;
       else if (this.active === preview) this.active = undefined;
       void vscode.commands.executeCommand('setContext', 'archifyPreviewFocus', Boolean(this.active));
+      if (preview.panel.active) void vscode.commands.executeCommand('setContext', 'archify.inModel', Boolean(preview.root));
     };
     preview.panel.onDidChangeViewState(onViewState);
     onViewState();

src/webview/messages.ts

@@ -9,6 +9,7 @@ export type WebviewMessage =
   | { type: 'openExternal'; href: string }
   | { type: 'openRelative'; href: string }
   | { type: 'openSource'; path: string; line?: number; endLine?: number; href?: string }
+  | { type: 'openDiagram'; path: string }
   | { type: 'error'; message: string };
 
 /** Column for opening files next to a webview without covering it. */
@@ -92,6 +93,8 @@ export async function handleWebviewMessage(
         vscode.window.showErrorMessage(`Archify: ${message.message}`);
         break;
       case 'hash':
+      case 'openDiagram':
+        // Handled by the view, which knows the model root.
         break;
     }
   } catch (error) {

src/webview/page.ts

@@ -14,8 +14,14 @@ export interface PageOptions {
   notice?: { text: string; kind: 'info' | 'warning' | 'error' };
   /** The 3D viewer script (a webview URI), added to Archify pages. */
   viewer3d?: { scriptUri: string; defaultView: '2d' | '3d' };
+  /** Node id → diagram path (relative to the model root); double-click opens it. */
+  links?: Record<string, string>;
+  /** The model page: metadata above the diagram, the diagram list and registry below. */
+  model?: ModelPanel;
 }
 
+import type { ModelPanel } from '../model/panel';
+
 export function makeNonce(): string {
   const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
   let nonce = '';
@@ -66,6 +72,8 @@ function bridgeScript(options: PageOptions): string {
     state: options.state,
     notice: options.notice,
     defaultView: options.viewer3d?.defaultView,
+    links: options.links ?? {},
+    model: options.model,
   };
   return `(function () {
   var config = ${scriptJson(config)};
@@ -162,10 +170,98 @@ function bridgeScript(options: PageOptions): string {
     (document.body || document.documentElement).appendChild(bar);
   }
 
+  // A node that links to another diagram opens it on double-click.
+  document.addEventListener('dblclick', function (event) {
+    var target = event.target;
+    var node = target && target.closest ? target.closest('[data-node-id]') : null;
+    if (!node) return;
+    var id = node.getAttribute('data-node-id');
+    if (id && config.links[id]) {
+      event.preventDefault();
+      event.stopPropagation();
+      post({ type: 'openDiagram', path: config.links[id] });
+    }
+  }, true);
+
+  function el(tag, className, text) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+
+  // The model page: metadata first, the diagram (if any) where Archify put
+  // it, then the diagrams of the model and the registry.
+  function renderModel(model) {
+    if (!model) return;
+    var anchor = document.querySelector('.container');
+    var head = el('section', 'archify-model archify-model-head');
+    head.appendChild(el('div', 'archify-model-kicker', 'Model' + (model.meta.id ? ' · ' + model.meta.id : '')));
+    head.appendChild(el('h1', 'archify-model-name', model.meta.name || model.meta.id || 'Untitled model'));
+    if (model.meta.description) head.appendChild(el('p', 'archify-model-description', model.meta.description.trim()));
+    if (model.nested.length) head.appendChild(el('p', 'archify-model-problem', 'Nested main.archify files are not supported and were ignored: ' + model.nested.join(', ')));
+    model.problems.forEach(function (problem) { head.appendChild(el('p', 'archify-model-problem', problem)); });
+    if (anchor && anchor.parentNode) anchor.parentNode.insertBefore(head, anchor); else document.body.appendChild(head);
+
+    var body = el('section', 'archify-model archify-model-body');
+    var count = model.groups.reduce(function (n, g) { return n + g.diagrams.length; }, 0);
+    body.appendChild(el('h2', 'archify-model-title', 'Diagrams' + (count ? ' · ' + count : '')));
+    if (!count) body.appendChild(el('p', 'archify-model-empty', 'No diagrams yet. Add .archify files next to main.archify or in subfolders.'));
+    model.groups.forEach(function (group) {
+      if (group.group) body.appendChild(el('h3', 'archify-model-group', group.group));
+      var list = el('ul', 'archify-model-list');
+      group.diagrams.forEach(function (diagram) {
+        var item = el('li', 'archify-model-item' + (diagram.parseError ? ' is-broken' : ''));
+        var button = el('button', 'archify-model-open');
+        button.type = 'button';
+        button.title = diagram.path;
+        button.appendChild(el('span', 'archify-model-item-title', diagram.title || diagram.path.split('/').pop()));
+        button.appendChild(el('span', 'archify-model-item-meta', diagram.parseError ? 'does not parse: ' + diagram.parseError : (diagram.kind || 'diagram') + ' · ' + diagram.path));
+        button.addEventListener('click', function () { post({ type: 'openDiagram', path: diagram.path }); });
+        item.appendChild(button);
+        list.appendChild(item);
+      });
+      body.appendChild(list);
+    });
+    if (model.registry.length) {
+      body.appendChild(el('h2', 'archify-model-title', 'Registry · ' + model.registry.length));
+      var table = el('table', 'archify-model-registry');
+      model.registry.forEach(function (element) {
+        var row = el('tr');
+        var name = el('td', 'archify-model-element');
+        name.appendChild(el('strong', '', element.label || element.id));
+        name.appendChild(el('span', 'archify-model-item-meta', element.id + (element.type ? ' · ' + element.type : '')));
+        row.appendChild(name);
+        row.appendChild(el('td', 'archify-model-element-description', element.description || ''));
+        var used = el('td', 'archify-model-used');
+        if (element.usedIn.length) {
+          element.usedIn.forEach(function (path) {
+            var link = el('button', 'archify-model-used-link', path.replace(/\.archify$/, ''));
+            link.type = 'button';
+            link.title = path;
+            link.addEventListener('click', function () { post({ type: 'openDiagram', path: path }); });
+            used.appendChild(link);
+          });
+        } else used.appendChild(el('span', 'archify-model-item-meta', 'not used yet'));
+        row.appendChild(used);
+        table.appendChild(row);
+      });
+      body.appendChild(table);
+    }
+    if (anchor && anchor.parentNode) anchor.parentNode.insertBefore(body, anchor.nextSibling); else document.body.appendChild(body);
+  }
+
   window.addEventListener('message', function (event) {
     var message = event.data || {};
     if (message.type === 'notice') showNotice(message.notice);
   });
+  if (config.model) {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', function () { renderModel(config.model); });
+    } else {
+      renderModel(config.model);
+    }
+  }
   if (config.notice) {
     if (document.readyState === 'loading') {
       document.addEventListener('DOMContentLoaded', function () { showNotice(config.notice); });
@@ -176,6 +272,33 @@ function bridgeScript(options: PageOptions): string {
 })();`;
 }
 
+const MODEL_STYLE = `
+.archify-model { --m-text: var(--text, var(--vscode-foreground)); --m-muted: var(--text-muted, var(--vscode-descriptionForeground)); --m-panel: var(--panel, var(--vscode-editorWidget-background)); --m-border: var(--panel-border, var(--vscode-editorWidget-border, rgba(128,128,128,.35))); --m-accent: var(--frontend-stroke, var(--vscode-textLink-foreground));
+  max-width: 1400px; margin: 0 auto; padding: 1.25rem 2rem; color: var(--m-text); font-family: var(--vscode-font-family, system-ui, sans-serif); }
+.archify-model-head { padding-top: 1.5rem; }
+.archify-model-kicker { font-size: 0.6875rem; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; color: var(--m-accent); }
+.archify-model-name { margin: 0.25rem 0 0.5rem; font-size: 1.5rem; font-weight: 700; letter-spacing: -0.02em; }
+.archify-model-description { margin: 0; max-width: 72ch; font-size: 0.9375rem; line-height: 1.55; color: var(--m-muted); white-space: pre-line; }
+.archify-model-problem { margin: 0.75rem 0 0; padding: 0.5rem 0.75rem; border-radius: 0.5rem; border: 1px solid var(--vscode-inputValidation-errorBorder, #be1100); color: var(--m-text); font-size: 0.8125rem; }
+.archify-model-title { margin: 1.5rem 0 0.75rem; font-size: 0.875rem; font-weight: 600; letter-spacing: 0.02em; }
+.archify-model-group { margin: 1rem 0 0.25rem; font-size: 0.6875rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--m-muted); font-family: ui-monospace, Menlo, monospace; }
+.archify-model-list { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 0.5rem; }
+.archify-model-open { display: flex; flex-direction: column; gap: 0.2rem; width: 100%; padding: 0.7rem 0.85rem; text-align: left; cursor: pointer; font: inherit; color: var(--m-text); background: var(--m-panel); border: 1px solid var(--m-border); border-radius: 0.6rem; transition: border-color 0.15s, transform 0.15s; }
+.archify-model-open:hover { border-color: var(--m-accent); transform: translateY(-1px); }
+.archify-model-open:focus-visible { outline: 2px solid var(--m-accent); outline-offset: 2px; }
+.archify-model-item.is-broken .archify-model-open { border-style: dashed; }
+.archify-model-item-title { font-weight: 600; font-size: 0.9375rem; }
+.archify-model-item-meta { font-size: 0.75rem; color: var(--m-muted); font-family: ui-monospace, Menlo, monospace; }
+.archify-model-empty { color: var(--m-muted); }
+.archify-model-registry { width: 100%; border-collapse: collapse; font-size: 0.875rem; }
+.archify-model-registry td { padding: 0.55rem 0.6rem; border-top: 1px solid var(--m-border); vertical-align: top; }
+.archify-model-element { width: 22%; } .archify-model-element strong { display: block; }
+.archify-model-element-description { color: var(--m-muted); line-height: 1.45; }
+.archify-model-used { width: 28%; display: flex; flex-wrap: wrap; gap: 0.3rem; }
+.archify-model-used-link { font: inherit; font-size: 0.75rem; padding: 0.15rem 0.5rem; border-radius: 999px; border: 1px solid var(--m-border); background: transparent; color: var(--m-text); cursor: pointer; font-family: ui-monospace, Menlo, monospace; }
+.archify-model-used-link:hover { border-color: var(--m-accent); }
+`;
+
 const NOTICE_STYLE = `
 .archify-vscode-notice {
   position: fixed; left: 12px; right: 12px; bottom: 12px; z-index: 2147483647;
@@ -197,7 +320,7 @@ export function prepareDiagramHtml(html: string, options: PageOptions): string {
   const head =
     `<meta http-equiv="Content-Security-Policy" content="${escapeHtml(contentSecurityPolicy(options.cspSource, options.nonce))}">\n` +
     `<script nonce="${options.nonce}">${bridgeScript(options)}</script>\n` +
-    `<style>${NOTICE_STYLE}</style>\n`;
+    `<style>${NOTICE_STYLE}${options.model ? MODEL_STYLE : ''}</style>\n`;
 
   let page = html
     // Drop any CSP the file brings along; ours is the one that applies.
@@ -220,6 +343,25 @@ export function prepareDiagramHtml(html: string, options: PageOptions): string {
   return page;
 }
 
+/** The model page for a main.archify without a diagram of its own. */
+export function modelPage(options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>, model: ModelPanel): string {
+  const bridge = bridgeScript({ cspSource: options.cspSource, nonce: options.nonce, theme: undefined, state: options.state, model, links: {} });
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta http-equiv="Content-Security-Policy" content="${escapeHtml(contentSecurityPolicy(options.cspSource, options.nonce))}">
+<script nonce="${options.nonce}">${bridge}</script>
+<style>
+  body { margin: 0; color: var(--vscode-foreground); background: var(--vscode-editor-background); }
+  ${MODEL_STYLE}
+</style>
+</head>
+<body></body>
+</html>`;
+}
+
 /** A small VS Code-styled page for loading and error states. */
 export function messagePage(
   options: Pick<PageOptions, 'cspSource' | 'nonce' | 'state'>,