feat: add section navigation and embedded Archify diagrams

scripts/build-diagrams.mjs

@@ -0,0 +1,30 @@
+import {readdirSync, readFileSync, mkdirSync, copyFileSync, renameSync, rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {execFileSync} from 'node:child_process';
+const cli = 'vendor/archify/bin/archify.mjs';
+const types = new Set(['architecture','workflow','sequence','dataflow','lifecycle']);
+// This directory is generated-only and ignored by Git. Remove stale artifacts.
+rmSync('static/diagrams', {recursive: true, force: true});
+mkdirSync('static/diagrams', {recursive: true});
+mkdirSync('.cache/archify', {recursive: true});
+const names = new Set();
+for (const file of readdirSync('diagrams').sort()) {
+  const match = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.([a-z]+)\.json$/.exec(file);
+  if (!match || !types.has(match[2])) throw new Error(`Unsupported diagram source: ${file}`);
+  const [,name,type] = match;
+  if (names.has(name)) throw new Error(`Duplicate diagram output: ${name}`);
+  names.add(name);
+  const input = join('diagrams',file);
+  const spec = JSON.parse(readFileSync(input,'utf8'));
+  const output = `static/diagrams/${name}/index.html`;
+  mkdirSync(`static/diagrams/${name}`, {recursive: true});
+  if (spec.diagram_type !== type || spec.meta.output !== output) throw new Error(`Diagram type/output mismatch: ${file}`);
+  const run = args => execFileSync(process.execPath,[cli,...args],{stdio:'inherit',env:{...process.env,ARCHIFY_UPDATE_CHECK_DISABLED:'1'}});
+  run(['validate',type,input,'--quality','showcase','--json']);
+  run(['deliver',type,input,output,'--quality','showcase','--json']);
+  run(['check',output,'--json','--require-provenance']);
+  renameSync(`static/diagrams/${name}/index.delivery.json`, `.cache/archify/${name}.delivery.json`);
+  copyFileSync(input,`static/diagrams/${name}.json`);
+}
+copyFileSync('vendor/archify/LICENSE','static/diagrams/ARCHIFY-LICENSE.txt');
+copyFileSync('vendor/archify/THIRD_PARTY_NOTICES.md','static/diagrams/THIRD-PARTY-NOTICES.md');

scripts/portal.test.mjs

@@ -0,0 +1,38 @@
+import {test} from 'node:test';
+import {createHash} from 'node:crypto';
+import assert from 'node:assert/strict';
+import {readFileSync, existsSync} from 'node:fs';
+const read = p => readFileSync(p, 'utf8');
+test('vendored source matches the reviewed upstream snapshot', () => {
+  const checksums = JSON.parse(read('vendor/archify-checksums.json'));
+  for (const [path, hash] of Object.entries(checksums)) {
+    assert.equal(createHash('sha256').update(readFileSync(`vendor/archify/${path}`)).digest('hex'), hash, path);
+  }
+});
+test('three independent section menus and Structure first', () => {
+  const config = read('docusaurus.config.ts');
+  for (const section of ['Organization', 'Strategy', 'Contribution']) assert(config.includes(`label: '${section}'`));
+  assert(!config.includes("label: 'Documentation'"));
+  assert(!config.includes("label: 'Maintainer guide'"));
+  assert(read('sidebars/organization.ts').includes("organizationSidebar: ['structure']"));
+  for (const section of ['organization','strategy','contribution']) assert(config.includes(`id: '${section}'`));
+});
+test('Archify is pinned, licensed and rebuilt, not a remote embed', () => {
+  const provenance = JSON.parse(read('vendor/archify-provenance.json'));
+  assert.equal(provenance.commit, 'd5a1333d7447c866a765adac7d4d062f2f02e4d2');
+  assert(read('vendor/archify/LICENSE').includes('MIT License'));
+  const scripts = JSON.parse(read('package.json')).scripts;
+  assert(scripts.build.startsWith('pnpm diagrams:build'));
+  const wrapper = read('src/components/ArchifyDiagram/index.tsx');
+  assert(wrapper.includes('sandbox="allow-scripts allow-downloads"'));
+  assert(!wrapper.includes('allow-same-origin'));
+  assert(wrapper.includes('useBaseUrl'));
+});
+test('example is explicitly illustrative and contains valid connected nodes', () => {
+  const spec = JSON.parse(read('diagrams/organization-structure.architecture.json'));
+  assert(spec.meta.title.includes('Illustrative'));
+  const ids = new Set(spec.components.map(n => n.id));
+  assert.equal(ids.size, spec.components.length);
+  for (const edge of spec.connections) assert(ids.has(edge.from) && ids.has(edge.to));
+  assert(read('docs/organization/structure.mdx').includes('not Eldorado’s confirmed organization chart'));
+});

scripts/verify.mjs

@@ -6,7 +6,7 @@ const config = read('docusaurus.config.ts');
 assert(config.includes("baseUrl: '/eldorado-v1/documentation/'"));
 assert(config.includes("onBrokenLinks: 'throw'"));
 assert(config.includes("hashed: 'filename'"));
-for (const file of readdirSync('docs')) {
+for (const file of readdirSync('docs', {recursive: true}).filter(f => /\.mdx?$/.test(f))) {
   const doc = read(join('docs', file));
   assert(/^---\n[\s\S]*?title: .+\n[\s\S]*?description: .+\n/.test(doc), `Missing metadata: ${file}`);
 }
@@ -16,9 +16,13 @@ const workflow = read('.gitea/workflows/pages.yml');
 assert(workflow.includes('mountpoint -q'));
 assert(workflow.includes("gitea.event_name == 'push' && gitea.ref == 'refs/heads/main'"));
 if (process.argv.includes('--build')) {
-  for (const route of ['index.html','docs/overview/index.html','docs/maintain/index.html','docs/reference/index.html','404.html']) {
+  for (const route of ['index.html','docs/overview/index.html','docs/maintain/index.html','docs/reference/index.html','404.html','organization/structure/index.html','strategy/index.html','contribution/index.html','contribution/diagrams/index.html','diagrams/organization-structure/index.html']) {
     assert(existsSync(join('build',route)), `Missing route: ${route}`);
   }
+  assert(!readdirSync('build/diagrams', {recursive: true}).some(f => f.endsWith('.delivery.json')), 'Private build receipts must not be published');
+  const diagram = read('build/diagrams/organization-structure/index.html');
+  assert(diagram.includes('Example leadership') && diagram.includes('node-engineering'));
+  assert(!diagram.includes('/opt/data/'), 'No build paths in published diagrams');
   const home = read('build/index.html');
   assert(/<title\b[^>]*>Eldorado Powered By AI<\/title>/.test(home));
   assert(home.includes('Powered By AI</span></h1>'));