Merge pull request 'Release 0.5.2: Archify menu section at the bottom, commands named "Archify | …"' (#18) from fix/archify-menu-section into main

All eight commands drop the Archify category and carry the prefix in the
title, so menus, the editor title bar and the Command Palette read the
same. The right-click group is zzz_archify: VS Code has a built-in
z_commands group that would otherwise sort after it.

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.2 — 2026-10-10
+
+- **Right-click menus:** the Archify commands (Archify | New Diagram…, Archify | Open Preview, Archify | Render to HTML File…, Archify | Open in HTML Viewer) now sit in their own section at the very bottom of the Explorer and editor-tab menus, instead of between New File, New Folder and the other built-in entries.
+- **All commands are named "Archify | …"**, the same in right-click menus, the editor title bar and the Command Palette: Archify | New Diagram… (was *New Diagram Archify…*), Archify | Open Preview, Archify | Open Preview to the Side, Archify | Render to HTML File…, Archify | Open in HTML Viewer, Archify | Open in Browser, Archify | Refresh Preview, Archify | Show Source.
+
+## 0.5.1 — 2026-10-07
+
+- **Clearer descriptions:** the Marketplace description, README and messages now say plainly that diagrams are `.archify` files in YAML. Archify's own JSON files (`*.architecture.json`, …) and rendered HTML are described as also supported, in their own section.
+- The rendered-HTML editor is now called **Archify HTML Viewer** (was *Archify Diagram Viewer*, the same name as the extension), and its command **Open in Archify HTML Viewer**.
+- Messages: "open a .archify diagram first"; an empty or broken `.archify` file asks for valid YAML, not JSON.
+
 ## 0.5.0 — 2026-10-04
 
 - **Brand completion:** after `brand:` in `.archify` files and Archify JSON sources, the editor suggests the 107 built-in brand IDs with their product names. Aliases and product names match too (`kafka` → `apache-kafka`, `postgres` → `postgresql`).

README.md

@@ -1,14 +1,24 @@
 # Archify Diagram Viewer
 
-View [Archify](https://github.com/tt-a1i/archify) diagrams inside VS Code. Click a `.archify` file (YAML) and the interactive diagram opens straight away; open its source beside it and the diagram follows your edits. Rendered Archify HTML files open in a viewer tab instead of a browser.
+Create and view [Archify](https://github.com/tt-a1i/archify) diagrams inside VS Code. You write a diagram as a **`.archify` file in YAML**; clicking it opens the interactive diagram, and the diagram follows your edits as you type.
 
 ![An Archify workflow diagram as shown by the preview](docs/preview.png)
 
 This is an unofficial extension. It bundles the Archify renderer (MIT, © tt-a1i) and runs it on VS Code's own Node runtime, so nothing else needs to be installed.
 
+## Supported files
+
+| File | Format | What the extension does |
+|---|---|---|
+| **`name.archify`** | **YAML** (the main format) | Opens as the interactive diagram. Show Source, live updates, validation, completion, templates. |
+| `name.architecture.json`, `name.workflow.json`, `name.sequence.json`, `name.dataflow.json`, `name.lifecycle.json` | JSON (Archify's own CLI format) | Opens as text, with a preview beside it and validation. For files produced by the Archify CLI or AI agents. |
+| Rendered Archify `.html` | HTML | Read-only viewer instead of a browser. |
+
+New diagrams should be `.archify` files; everything below describes them unless it says otherwise.
+
 ## Quick start
 
-The fastest start: right-click a folder in the Explorer and choose **New Diagram Archify…** (also in *File → New File…* and the Command Palette). Pick a kind of diagram (Architecture, Workflow, Sequence, Data Flow, Lifecycle or Everyday Plan), give it a name, and a small working `.archify` file is created and opened. Change its YAML to fit your case.
+The fastest start: right-click a folder in the Explorer and choose **Archify | New Diagram…** (also in *File → New File…* and the Command Palette). Pick a kind of diagram (Architecture, Workflow, Sequence, Data Flow, Lifecycle or Everyday Plan), give it a name, and a small working `.archify` file is created and opened. Change its YAML to fit your case.
 
 To write one by hand:
 
@@ -36,31 +46,35 @@ The same file is in [examples/hello.archify](examples/hello.archify).
 
 ## The `.archify` format
 
-A `.archify` file is an Archify diagram source written in **YAML**. It has the same fields as the JSON the Archify CLI renders, and plain JSON content still works, since JSON is valid YAML. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`.
+A `.archify` file is an Archify diagram written in **YAML**. Its fields are those of Archify's diagram schema; the extension converts the YAML for the renderer, so you never handle JSON yourself. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`.
 
 - **Opening:** the **Archify Diagram** editor is the default for `.archify`. Use *Reopen Editor With… → Text Editor* to edit the YAML full-screen.
 - **Completion:** with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (`redhat.vscode-yaml`) installed, `.archify` files get completion and hover from Archify's schemas. The schema follows `diagram_type`.
 
-Archify's own JSON naming, `name.architecture.json`, `name.workflow.json` and so on, works too. Those open as text with a preview button, and get schema help from VS Code's built-in JSON support.
+`.archify` files from extension version 0.2.0 were written in JSON. They still open, because JSON is valid YAML, but new files should use YAML.
+
+## Archify's JSON files
+
+The Archify CLI and the AI agents that use it write diagrams as JSON, named `name.architecture.json`, `name.workflow.json` and so on. The extension supports these too: they open as text with a preview button in the editor title (<kbd>Cmd/Ctrl+K V</kbd> to the side, <kbd>Cmd/Ctrl+Shift+V</kbd> in place), get validation in Problems, and get schema completion from VS Code's built-in JSON support. Any other `.json` file that declares an Archify `diagram_type` previews the same way.
 
 ## Features
 
-- **New diagram from a template**: *New Diagram Archify…* creates a starter `.archify` file for any of the five diagram kinds, or an everyday plan, in the chosen folder.
+- **New diagram from a template**: *Archify | New Diagram…* creates a starter `.archify` file for any of the five diagram kinds, or an everyday plan, in the chosen folder.
 - **Diagram editor**: `.archify` files open as the rendered diagram. **Show Source** opens the YAML beside it, and edits re-render live.
-- **Live preview**: for Archify's `*.architecture.json`-style files, or any JSON with a `diagram_type`. Use the preview button in the editor title, <kbd>Cmd/Ctrl+K V</kbd> (to the side) or <kbd>Cmd/Ctrl+Shift+V</kbd>. The preview keeps the focus and route you selected (`#focus=…`, `#route=…`) when it re-renders.
-- **HTML viewer**: right-click a rendered `.html` file and choose **Open in Archify Viewer**, or use *Reopen Editor With… → Archify Diagram Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk.
-- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the source.
+- **Live updates**: the diagram re-renders as you edit, and keeps the focus and route you selected (`#focus=…`, `#route=…`).
+- **HTML viewer**: right-click a rendered `.html` file and choose **Archify | Open in HTML Viewer**, or use *Reopen Editor With… → Archify HTML Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk.
+- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the `.archify` file.
 - **Brand logos**: after `brand:` the editor suggests Archify's built-in brand IDs (PostgreSQL, Redis, Kafka, Docker, …). Typing an alias or product name finds them too, so `kafka` offers `apache-kafka`. An unknown brand is reported on its own line.
-- **Schema help**: completion and hover come from Archify's own schemas: built in for the JSON files, and through the YAML extension for `.archify` files.
+- **Schema help**: completion and hover from Archify's own schemas, through the YAML extension for `.archify` files.
 - **Source links**: in source-backed diagrams, clicking a source reference opens that file and line range in the editor. If the file is not in the workspace, the web link opens instead.
 - **Export**: the diagram's own Export menu (PNG, SVG, share card, …) saves through a VS Code save dialog.
-- **Commands**: *New Diagram Archify…*, *Archify: Render to HTML File…*, *Archify: Open in Browser*, *Archify: Refresh Preview*, *Archify: Show Source*.
+- **Commands**: *Archify | New Diagram…*, *Archify | Render to HTML File…*, *Archify | Open in Browser*, *Archify | Refresh Preview*, *Archify | Show Source*.
 
 ## Source evidence
 
 A diagram that declares `meta.repository` and `sources` is verified against a local Git checkout whose `origin` and pinned commit match. The extension uses the Git top-level directory of the diagram file, or `archify.repoRoot` when set.
 
-When verification fails, the default (`archify.sourceEvidence: "fallback"`) still shows the diagram without source links, explains why in a notice, and reports the reason as a warning. Set it to `"strict"` to treat this as an error, as the Archify CLI does. *Render to HTML File…* always verifies strictly and asks before rendering without source links.
+When verification fails, the default (`archify.sourceEvidence: "fallback"`) still shows the diagram without source links, explains why in a notice, and reports the reason as a warning. Set it to `"strict"` to treat this as an error, as the Archify CLI does. *Archify | Render to HTML File…* always verifies strictly and asks before rendering without source links.
 
 ## Settings
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "archify-vscode-ext",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "archify-vscode-ext",
-      "version": "0.5.0",
+      "version": "0.5.2",
       "license": "MIT",
       "dependencies": {
         "yaml": "^2.9.1"

package.json

@@ -1,8 +1,8 @@
 {
   "name": "archify-vscode-ext",
   "displayName": "Archify Diagram Viewer",
-  "description": "Visualize Archify diagrams: .archify files (YAML) open straight into the interactive diagram; also previews Archify JSON sources and rendered Archify HTML inside VS Code.",
-  "version": "0.5.0",
+  "description": "Archify diagrams in VS Code. Write diagrams as .archify files in YAML: they open as the interactive diagram, with live updates, validation, templates and completion. Also previews Archify's own JSON files (*.architecture.json, \u2026) and opens rendered Archify HTML.",
+  "version": "0.5.2",
   "publisher": "root-at-skic",
   "license": "MIT",
   "icon": "media/icon.png",
@@ -23,6 +23,7 @@
   ],
   "keywords": [
     "archify",
+    "yaml",
     "diagram",
     "architecture",
     "sequence",
@@ -40,49 +41,42 @@
     "commands": [
       {
         "command": "archify.newDiagram",
-        "title": "New Diagram Archify\u2026",
+        "title": "Archify | New Diagram\u2026",
         "icon": "$(new-file)"
       },
       {
         "command": "archify.showPreview",
-        "title": "Open Preview",
-        "category": "Archify",
+        "title": "Archify | Open Preview",
         "icon": "$(open-preview)"
       },
       {
         "command": "archify.showPreviewToSide",
-        "title": "Open Preview to the Side",
-        "category": "Archify",
+        "title": "Archify | Open Preview to the Side",
         "icon": "$(open-preview)"
       },
       {
         "command": "archify.openHtmlViewer",
-        "title": "Open in Archify Viewer",
-        "category": "Archify",
+        "title": "Archify | Open in HTML Viewer",
         "icon": "$(open-preview)"
       },
       {
         "command": "archify.renderToHtml",
-        "title": "Render to HTML File\u2026",
-        "category": "Archify",
+        "title": "Archify | Render to HTML File\u2026",
         "icon": "$(file-code)"
       },
       {
         "command": "archify.openInBrowser",
-        "title": "Open in Browser",
-        "category": "Archify",
+        "title": "Archify | Open in Browser",
         "icon": "$(globe)"
       },
       {
         "command": "archify.refreshPreview",
-        "title": "Refresh Preview",
-        "category": "Archify",
+        "title": "Archify | Refresh Preview",
         "icon": "$(refresh)"
       },
       {
         "command": "archify.showSource",
-        "title": "Show Source",
-        "category": "Archify",
+        "title": "Archify | Show Source",
         "icon": "$(go-to-file)"
       }
     ],
@@ -153,29 +147,29 @@
         {
           "command": "archify.newDiagram",
           "when": "explorerResourceIsFolder",
-          "group": "navigation@10"
+          "group": "zzz_archify@1"
         },
         {
           "command": "archify.showPreview",
           "when": "resourceFilename =~ /(\\.archify|\\.(architecture|workflow|sequence|dataflow|lifecycle)\\.json)$/",
-          "group": "navigation@20"
+          "group": "zzz_archify@2"
         },
         {
           "command": "archify.renderToHtml",
           "when": "resourceFilename =~ /(\\.archify|\\.(architecture|workflow|sequence|dataflow|lifecycle)\\.json)$/",
-          "group": "navigation@21"
+          "group": "zzz_archify@3"
         },
         {
           "command": "archify.openHtmlViewer",
           "when": "resourceExtname == .html",
-          "group": "navigation@20"
+          "group": "zzz_archify@2"
         }
       ],
       "editor/title/context": [
         {
           "command": "archify.showPreview",
           "when": "resourceFilename =~ /(\\.archify|\\.(architecture|workflow|sequence|dataflow|lifecycle)\\.json)$/",
-          "group": "1_open"
+          "group": "zzz_archify@1"
         }
       ],
       "file/newFile": [
@@ -212,7 +206,7 @@
       },
       {
         "viewType": "archify.htmlViewer",
-        "displayName": "Archify Diagram Viewer",
+        "displayName": "Archify HTML Viewer",
         "selector": [
           {
             "filenamePattern": "*.html"

src/extension.ts

@@ -35,7 +35,7 @@ export function activate(context: vscode.ExtensionContext): void {
 
   function sourceUri(arg?: unknown): vscode.Uri | undefined {
     const uri = targetUri(arg);
-    if (!uri) vscode.window.showWarningMessage('Archify: open a diagram JSON source first.');
+    if (!uri) vscode.window.showWarningMessage('Archify: open a .archify diagram first.');
     return uri;
   }
 
@@ -119,7 +119,7 @@ export function activate(context: vscode.ExtensionContext): void {
     vscode.commands.registerCommand('archify.newDiagram', async (arg?: unknown) => {
       const template = await vscode.window.showQuickPick(
         TEMPLATES.map((item) => ({ label: item.label, description: item.description, template: item })),
-        { title: 'New Diagram Archify', placeHolder: 'Kind of diagram' },
+        { title: 'Archify | New Diagram', placeHolder: 'Kind of diagram' },
       );
       if (!template) return;
       const { file, defaultName } = template.template;
@@ -128,7 +128,7 @@ export function activate(context: vscode.ExtensionContext): void {
       let target: vscode.Uri | undefined;
       if (folder) {
         const name = await vscode.window.showInputBox({
-          title: 'New Diagram Archify',
+          title: 'Archify | New Diagram',
           prompt: `File name in ${vscode.workspace.asRelativePath(folder, true)}`,
           value: defaultName,
           validateInput: async (value) =>
@@ -140,7 +140,7 @@ export function activate(context: vscode.ExtensionContext): void {
       } else {
         // No workspace: let the user choose where to save.
         target = await vscode.window.showSaveDialog({
-          title: 'New Diagram Archify',
+          title: 'Archify | New Diagram',
           filters: { 'Archify Diagram': ['archify'] },
           saveLabel: 'Create',
         });

src/preview.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import * as vscode from 'vscode';
-import { readDiagramSource } from './detect';
+import { isArchifyFile, readDiagramSource } from './detect';
 import { renderDiagram } from './renderer';
 import { evidenceMode, log, readText, runtimeFor, viewerTheme } from './runtime';
 import { handleWebviewMessage, WebviewMessage } from './webviewMessages';
@@ -100,7 +100,7 @@ class DiagramPreview implements vscode.Disposable {
     if (!source) {
       this.showMessage(
         'Nothing to show yet',
-        'Set "diagram_type" to architecture, workflow, sequence, dataflow or lifecycle, and make sure the file is valid JSON.',
+        `Set "diagram_type" to architecture, workflow, sequence, dataflow or lifecycle, and make sure the file is valid ${isArchifyFile(this.uri.path) ? 'YAML' : 'JSON'}.`,
       );
       return;
     }

test/integration/suite.ts

@@ -97,11 +97,11 @@ export async function run(): Promise<void> {
     assert.ok(diagnostics[0].range.start.line >= 2, `reported on line ${diagnostics[0].range.start.line + 1}`);
   });
 
-  await check('New Diagram Archify creates a .archify file from a template and opens the diagram', async () => {
+  await check('Archify | New Diagram creates a .archify file from a template and opens the diagram', async () => {
     // Menus show the bare title, so it must name Archify by itself.
     const commands = vscode.extensions.getExtension(EXTENSION_ID)?.packageJSON.contributes.commands as { command: string; title: string; category?: string }[];
     const newDiagram = commands.find((item) => item.command === 'archify.newDiagram');
-    assert.equal(newDiagram?.title, 'New Diagram Archify…');
+    assert.equal(newDiagram?.title, 'Archify | New Diagram…');
     assert.equal(newDiagram?.category, undefined);
     const folder = workspaceFile('.');
     // Stub the template pick and the name prompt; check the name validation on the way.