Pinega Web Gate 2: Documentation Reorganisation and Review

[likern]

Summary

Implements Gate 2 — Documentation Reorganisation and Review from the accepted Web content audit on top of merged Gate 1.

The former mixed Getting Started article is decomposed into a real documentation corpus with separate Start/Tutorial, How-to, Concepts/Explanation, Reference, and Contributing content. Native HTML remains the durable article-body source; content-registry schema v2 is the single discovery/navigation metadata contract.

Documentation corpus

/docs/
├── getting-started/                         orientation router
├── start/
│   ├── project-overview/
│   └── research-workspace/                 tutorial
├── how-to/
│   ├── build-the-site/
│   └── run-validation/
├── concepts/
│   ├── pinega-programme/
│   ├── pinega-engine-architecture/
│   ├── maturity-and-evidence-labels/
│   └── research-to-product-workflow/
├── reference/
│   ├── repository-layout/
│   ├── web-build-and-environment/
│   └── content-metadata-schema/
└── contributing/
    └── review-and-release-gates/

The schema reserves Tutorials as a first-class section, but no empty Tutorials landing is published merely to complete a taxonomy.

Content contract v2

Every documentation route carries:

• documentation.section;
• documentation.purpose;
• documentation.order;
• documentation.applies_to;
• documentation.related.

Build-time generation now owns repeated documentation chrome and discovery projections:

• grouped real-page cards on /docs/;
• documentation side navigation with aria-current;
• hierarchical breadcrumbs;
• visible purpose/maturity/applicability/update/owner provenance;
• source/edit and related-content links;
• content/documentation-manifest.json;
• documentation metadata in site-manifest.json.

Article prose remains native semantic HTML.

UX/content decisions

• /docs/getting-started/ is now orientation only; task procedures, explanations, tutorials, and reference data have explicit owners.
• the disabled pseudo-version selector is removed; the UI reports the real Research-stage corpus instead.
• /docs/ filters real canonical pages, not anchors or external placeholders.
• filtering is progressive enhancement: the complete grouped catalogue exists in static HTML without JavaScript; enhancement performs Unicode-normalised AND matching and collapses empty groups.
• the control remains Filter documentation topics; Gate 2 does not claim site-wide full-text search.
• every nested documentation page exposes visible provenance and applicability so architecture/design-contract material cannot be mistaken for a shipped product instruction.

Search/publishing readiness

content/documentation-manifest.json provides a stable documentation-only projection containing route, title, summary, section, purpose, applicability, topics, programme, maturity, update date, authors, and related IDs. Later Blog, paper/PDF, and site-wide-search gates can extend/consume the same route and discovery model instead of inventing a second catalogue.

Final validation

Final head:

bbf4b93f35d43fceecb8d0d53cdafef0b60039b0

All applicable final-head gates pass:

• Check Pinega Website — run 31194256719 — success;
• Scientific diagram review artifacts — run 31194257613 — success.

The Web gate passed token generation checks, strict TypeScript, unit/architecture contracts, static build and budgets, Chromium desktop/mobile, Firefox, WebKit, accessibility, committed visual baselines, checksums, and artifact upload.

The final website artifact was downloaded and its complete artifacts/SHA256SUMS.txt manifest verifies successfully.

Review artifacts

Website / documentation

Workflow run: 31194256719

Artifact: pinega-website-v0.2-pull_request

• artifact ID: 9000314796;
• digest: sha256:e1cae7bde67d66b6f943df277b103674428a166d7befdde1ec464fc6d9d16b89.

Primary visual-review baselines include:

• docs-corpus-chromium-desktop-linux.png;
• docs-project-overview-chromium-desktop-linux.png;
• getting-started-chromium-desktop-linux.png;
• docs-run-validation-chromium-desktop-linux.png;
• Pinega Engine architecture header/provenance surfaces;
• existing Gate 1 homepage, Technology, Research, About, and dark-mode surfaces.

The Gate 2 documentation surfaces were visually inspected after baseline generation; no blocking hierarchy, overflow, provenance, or composition defect remains.

Scientific Diagram Language compatibility

Workflow run: 31194257613

Artifact: scientific-diagrams-pr-22-bbf4b93f35d4-attempt-1

• artifact ID: 9000139634;
• digest: sha256:2be9ac41e0921e9553dba97ab9eb6931f6f99fa64d700098fe01c7f5c1313613.

This is a compatibility gate only: Gate 2 does not add a diagram family or promote a new layout.

Explicit non-goals

• no Blog route or publishing pipeline;
• no paper/PDF library integration;
• no Typst-to-HTML publication pipeline;
• no site-wide full-text search dependency or UI;
• no new Scientific Diagram Language family/layout;
• no Pinega Engine product-availability claim.

Status: ready for review.