feat: add section navigation and embedded Archify diagrams

docs/contribution/contribute.md

@@ -0,0 +1,19 @@
+---
+title: Contribute
+description: Contribute evidence, proposals, and documentation changes to Eldorado Powered By AI.
+slug: /
+---
+
+Use this section to contribute to **Eldorado Powered By AI**.
+
+- Distinguish evidence, proposals, open questions, and agreed decisions.
+- Do not present example diagrams as the actual organization or architecture.
+- Use a pull request for source changes; automated checks must pass before publication.
+
+## Maintain the portal
+
+[Update and publish the site](/docs/maintain/) or consult the [configuration reference](/docs/reference/).
+
+## Create diagrams
+
+[Author and embed an Archify diagram](./diagrams.md).

docs/contribution/diagrams.md

@@ -0,0 +1,46 @@
+---
+title: Archify diagrams
+description: Author typed JSON diagrams and embed their local interactive viewer in documentation.
+---
+
+## Capabilities
+
+[Archify](https://github.com/tt-a1i/archify) 3.0.1 is vendored at commit `d5a1333d7447c866a765adac7d4d062f2f02e4d2` under `vendor/archify/`, with its MIT license and third-party notices preserved.
+
+| Diagram type | Intended use |
+| --- | --- |
+| Architecture | Components, boundaries and relationships; also suitable for this illustrative structure test |
+| Workflow | Processes, branches and approval gates |
+| Sequence | Participants and ordered messages |
+| Dataflow | Sources, processing and destinations |
+| Lifecycle | States and transitions |
+
+The standalone viewer provides pan/zoom, node inspection, search/focus, relationship tracing, light/dark themes, and an export menu. Motion is opt-in. The Organization example exercises architecture mode; other diagram types use the same build interface but do not yet have portal-specific examples. Browser-dependent exports such as video are not acceptance-tested by this integration.
+
+## Author a diagram
+
+Create `diagrams/<name>.<type>.json` using the matching schema and authoring guidance in `vendor/archify/schemas/` and `vendor/archify/references/`. Use stable IDs, explicit relationships, and honest evidence labels. Do not include private information merely because the source repository is private: Pages access is a separate platform policy.
+
+Set `meta.output` to `static/diagrams/<name>/index.html`. The build validates the typed source with the upstream showcase profile, renders locally, checks the artifact, and publishes the standalone HTML and a downloadable JSON source.
+
+```sh
+pnpm diagrams:build
+pnpm test
+pnpm build
+```
+
+## Embed it in MDX
+
+```mdx
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<ArchifyDiagram name="organization-structure" title="Illustrative organization structure" />
+```
+
+Supply a text alternative below each diagram. The wrapper uses a local, base-path-aware iframe with a descriptive title, scripts and downloads enabled, and no same-origin or parent-navigation permissions. A full-viewer link provides a wider canvas. Generated output is ignored by Git and rebuilt in CI.
+
+## Integration boundaries
+
+The portal remains Docusaurus/React/TypeScript with pnpm. It uses the actual upstream renderer, not a look-alike diagram implementation. No Astro site, global agent installation, hosted rendering service, or AI API was added. The integration disables Archify update networking and does not run its installation commands.
+
+Upgrades are deliberate: review the upstream diff and licenses, update the provenance record and vendor checksums, then run tests, diagram validation, production build, and browser checks. Do not edit upstream files for portal styling.