diff --git a/docs/web-foundation.md b/docs/web-foundation.md
index 81b94ae..309bdb6 100644
--- a/docs/web-foundation.md
+++ b/docs/web-foundation.md
@@ -2,111 +2,168 @@
## Status
-Version: `0.2`
+Version: `0.3`
+
+The v0.1 gate established canonical cross-platform tokens, the Web Awesome
+integration boundary, the component laboratory, representative Pinega
+compositions, and executable quality gates. Version 0.2 added the first public
+homepage, documentation, research, and getting-started routes.
+
+Version 0.3 implements the Information Architecture Foundation accepted in
+`docs/web-content-audit.md`:
+
+- Pinega is presented as the umbrella database-systems research and engineering
+ programme rather than as a synonym for one storage engine;
+- Pinega Engine is the first active implementation programme beneath that
+ master brand;
+- public navigation owns Technology, Research, Documentation, About, and
+ GitHub destinations;
+- the component laboratory remains an internal validation surface;
+- a versioned content registry owns route and discovery metadata;
+- documentation exposes a topic filter and content-purpose labels without
+ claiming full-text search;
+- no new diagram family, blog engine, paper viewer, or Typst HTML pipeline is
+ introduced by this milestone.
+
+The working master-brand line is:
-The `0.1` gate established canonical cross-platform tokens, the Web Awesome
-integration boundary, the component laboratory, five representative Pinega
-compositions, and executable quality gates.
+```text
+Correctness under concurrency.
+```
+
+It is used as a technical positioning line, not as a claim that every proposed
+programme has reached formal verification or production maturity.
+
+## Public hierarchy
+
+```text
+Pinega / Pinega Labs programme and organisation boundary
+ ↓
+Technology programmes what may become maintained software
+ ↓
+Pinega Engine first active implementation programme
+
+Research questions, evidence, models, and experiments
+Documentation start, how-to, explanation, and reference paths
+About identity, principles, and commercial boundary
+```
+
+Current routes:
+
+```text
+/ master-brand homepage
+/technology/ programme catalogue and Pinega Engine boundary
+/research/ research taxonomy, method, and active studies
+/docs/ documentation topics and purpose/maturity labels
+/docs/getting-started/ first contributor-oriented start page
+/about/ Pinega and Pinega Labs identity
+/component-lab/ internal validation surface
+/404.html explicit not-found page
+```
+
+The blog is not placed in navigation before a real content model and route
+exist. Empty destination pages are prohibited.
-Version `0.2` adds the first public information architecture:
+## Content contract
+
+`web/content/content-index.json` is the only route and public-discovery
+registry. The schema records:
```text
-/ product homepage
-/docs/ documentation landing
-/docs/getting-started/ first documentation article
-/research/ research programme
-/component-lab/ design-system validation surface
+id, route, source/output paths, content type, titles, summary, audience,
+programme, research area, topics, maturity, dates, authors, sitemap,
+searchability, structured-data intent, public/canonical status
```
-The public pages remain research-stage communications. They explicitly
-separate available artefacts, validated design contracts, research hypotheses,
-and planned engine work.
+Page bodies remain native semantic HTML. The build validates agreement between
+registry and source pages, then derives routes, sitemap entries, and
+`site-manifest.json` from the registry.
+
+This boundary is intentionally reusable by later blog, paper, feed, JSON-LD,
+related-content, and static-search implementations. Those gates must extend the
+same metadata model rather than introducing parallel front matter or route
+lists without reconciliation.
## Principles
1. Native HTML owns document semantics and durable content.
2. CSS owns presentation, layout, responsive adaptation, and visual state.
-3. JavaScript owns domain state, lifecycle, and interaction orchestration.
+3. JavaScript owns lifecycle and interaction enhancement.
4. Web Awesome supplies generic interaction primitives, not Pinega semantics.
5. Pinega custom elements wrap only stable domain concepts or intentional
- vendor isolation boundaries.
+ vendor-isolation boundaries.
6. Licensed Pro components progressively enhance complete semantic fallbacks.
7. Canonical Pinega tokens generate CSS, TypeScript, and Typst adapters.
8. Product maturity is expressed with text and structure, never colour alone.
-9. Public claims distinguish implemented, validated, proposed, and planned work.
-
-## Layers
-
-```text
-@layer vendor,
- pinega.tokens,
- pinega.base,
- pinega.layout,
- pinega.webawesome,
- pinega.components,
- pinega.utilities,
- pinega.overrides;
-```
-
-Web Awesome retains its internal layers inside `vendor`. The Pinega adapter
-maps canonical tokens after vendor defaults, and component styling remains
-above that adapter.
+9. Public claims distinguish implemented, validated, experimental, proposed,
+ and planned work.
+10. Public navigation follows user intent and programme ownership, not repository
+ directories or internal validation surfaces.
## Page and build model
The site is a static multi-page build. Source HTML is not generated from a
-client-side framework and is useful before Custom Elements register.
+client-side framework and remains useful before Custom Elements register.
`web/scripts/build.mjs`:
-- bundles the shared CSS and JavaScript entrypoint;
-- copies each explicit page to a clean directory route;
-- injects the private Web Awesome project boundary when configured;
-- emits canonical URLs from `PINEGA_SITE_ORIGIN`;
-- generates `robots.txt`, `sitemap.xml`, and `site-manifest.json`;
-- copies Web Awesome assets and static Pinega assets.
-
-`web/scripts/serve.mjs` resolves directory indexes, rejects path traversal,
-supports `GET` and `HEAD`, and returns the generated not-found page with HTTP
-status 404.
+- validates the versioned content registry;
+- verifies title, description, page identity, canonical policy, heading count,
+ and public navigation for every registered source page;
+- bundles shared CSS and JavaScript;
+- injects semantic diagrams and the private Web Awesome project boundary;
+- emits clean directory routes from the registry;
+- copies canonical content, diagram, and static sources needed by consumers;
+- generates `robots.txt`, `sitemap.xml`, and a metadata-rich
+ `site-manifest.json`.
-## Component decision rule
+## Navigation decision rule
```text
-native element
- when HTML already owns the semantics and behavior
-
-direct wa-* element
- for a stable generic interaction primitive
+public primary navigation
+ stable audience destination with real content and route ownership
-Pinega composition
- when multiple generic primitives form a stable product pattern
+footer navigation
+ durable public destinations and repository access
-Pinega custom element
- for domain semantics, lifecycle, or vendor API isolation
+internal/contributor navigation
+ component lab, design-system validation, build and maintenance surfaces
```
-`pinega-doc-search` follows this rule: documentation cards are durable HTML;
-the Custom Element adds filtering and an aria-live result count without
-constructing or replacing the cards.
+`/component-lab/` remains out of the sitemap, public primary navigation, and
+future site search. It is reachable from contributor documentation.
+
+## Documentation and search boundary
+
+The current `pinega-doc-search` component filters eight durable topic cards.
+Its visible UI is therefore labelled **Filter documentation topics**. It does
+not claim indexed page search.
+
+The documentation cards expose purpose independently from maturity:
-## Pro boundary
+- Start;
+- How-to;
+- Explanation;
+- Research;
+- Reference.
-The licensed project is deployment configuration, not public source. No Pro
-assets or project credentials are committed. `pinega-benchmark` always retains
-an accessible HTML table. It renders a native SVG chart first and upgrades to
-Web Awesome Pro only after `wa-line-chart` is registered.
+A later documentation-reorganisation gate will split the first broad
+getting-started article into real pages. Site-wide static search follows only
+after the docs, blog, and paper corpus are large enough to justify an index.
## Gate exit criteria
-- generated token artifacts are deterministic and current;
-- no purchased project URL or license material is present in the repository;
-- TypeScript passes strict checking;
-- all public routes and the component laboratory build from the pinned dependency set;
-- local links, canonical metadata, sitemap entries, and 404 handling are validated;
-- semantic and keyboard browser tests pass in Chromium, Firefox, and WebKit;
-- serious and critical axe violations are absent on every public route;
-- mobile and desktop layouts have no horizontal overflow;
-- committed screenshots protect the homepage, docs, research, component lab,
- and representative dark-mode compositions;
-- public pages remain meaningful without the Pro project and without client-side content generation.
+- Pinega is framed as the master programme on homepage and metadata;
+- `Correctness under concurrency.` appears as the working brand line;
+- Pinega Engine is explicitly subordinate to the wider programme;
+- Technology and About routes contain substantive content;
+- Research exposes the accepted seven-area taxonomy;
+- public navigation is consistent on every public page and excludes the
+ component laboratory;
+- content metadata is versioned, validated, copied to output, and represented
+ in the generated site manifest;
+- all local routes and fragments resolve;
+- the topic-filter label matches actual behaviour;
+- the site remains useful without client-side rendering or Pro assets;
+- TypeScript, unit, build-budget, Chromium, Firefox, WebKit, accessibility,
+ responsive-overflow, and visual-regression gates pass.
diff --git a/docs/web-ia-foundation.md b/docs/web-ia-foundation.md
new file mode 100644
index 0000000..681e8c6
--- /dev/null
+++ b/docs/web-ia-foundation.md
@@ -0,0 +1,80 @@
+# Pinega Web IA Foundation
+
+Status: **CURRENT IMPLEMENTATION**
+Baseline: Information Architecture and Content Audit merged by PR #20
+Implementation branch: `agent/pinega-web-ia-foundation`
+
+## Purpose
+
+This milestone implements the first public information architecture for Pinega
+as an umbrella database-systems research, engineering, and future product
+programme. It changes the site's ownership model without introducing a blog,
+paper viewer, full-text search, Typst HTML output, or new scientific diagrams.
+
+## Accepted public model
+
+```text
+Pinega master technology and product programme
+Pinega Labs working research/engineering and future company identity
+Technology programmes candidate paths to maintained commercial software
+Pinega Engine first active implementation programme
+Research evidence, models, experiments, and open questions
+Documentation reproducible start/how-to/explanation/reference paths
+```
+
+The working brand line is:
+
+```text
+Correctness under concurrency.
+```
+
+The line is deliberately concise. It identifies the technical centre of Pinega
+without replacing maturity labels or evidence-based claims.
+
+## Implemented routes
+
+| Route | Ownership |
+|---|---|
+| `/` | Master-brand proposition, programme status, featured Pinega Engine, and evidence discipline |
+| `/technology/` | Technology catalogue, Pinega Engine architecture, accepted decisions, and promotion criteria |
+| `/research/` | Seven-area research catalogue, YDMP method, and existing active studies |
+| `/docs/` | Documentation-topic filter with purpose and maturity labels |
+| `/docs/getting-started/` | Programme boundary and reproducible workspace commands |
+| `/about/` | Pinega/Pinega Labs relationship, principles, current company boundary, and collaboration path |
+| `/component-lab/` | Internal validation surface, excluded from public discovery |
+
+## Content metadata
+
+`web/content/content-index.json` is the single route/discovery registry. Native
+HTML remains the body source. This avoids premature adoption of a CMS while
+establishing the metadata required by future publishing systems.
+
+The registry is expected to become input to:
+
+- blog indexes and feeds;
+- paper and research-artefact catalogues;
+- JSON-LD generation;
+- related-content navigation;
+- static full-text search;
+- author and update metadata;
+- sitemap and route validation.
+
+A later system may generate or import registry entries, but it must not create a
+second conflicting source of route identity.
+
+## Explicitly deferred work
+
+- Documentation article decomposition.
+- Blog content and RSS/Atom.
+- Original-paper and PDF integration.
+- Typst-to-HTML publication experiments.
+- Site-wide indexed search.
+- Contact or commercial-sales claims before a real company boundary exists.
+- New scientific-diagram families or candidate-profile promotion.
+
+## Next milestone
+
+After this gate is accepted, proceed to **Documentation Reorganisation and
+Review**. That work should split mixed documentation modes, establish real
+concept/how-to/reference pages, and evaluate the current filtering UX before
+adding the blog or a full-text search dependency.
diff --git a/web/README.md b/web/README.md
index f1b9273..dfce2f9 100644
--- a/web/README.md
+++ b/web/README.md
@@ -1,10 +1,65 @@
# Pinega Website and Strata Web System
-This directory contains the production-oriented web implementation of Pinega
-Strata. It uses semantic HTML, modern CSS, native Custom Elements, and Web
-Awesome as the generic interaction kernel.
+This directory contains Pinega's production-oriented static Web platform. It
+uses semantic HTML, modern CSS, native Custom Elements, and Web Awesome as the
+generic interaction kernel. Pinega Strata remains the canonical design system.
-## Architecture
+## Public information architecture
+
+The public site presents Pinega as an umbrella database-systems research and
+engineering programme. Pinega Engine is the first active implementation
+programme beneath that master brand.
+
+```text
+/ master-brand homepage
+/technology/ technology programmes and maturity boundaries
+/research/ research-area catalogue and active studies
+/docs/ documentation topics and content-type map
+/docs/getting-started/ first guided contributor path
+/about/ Pinega / Pinega Labs identity and principles
+/component-lab/ internal design-system validation surface
+/404.html explicit not-found page
+```
+
+`/component-lab/` remains buildable and testable but is excluded from primary
+public navigation, the sitemap, and future site search.
+
+## Content and route contract
+
+`content/content-index.json` is the versioned route and discovery registry. It
+owns page identity, route/output mapping, navigation, title, summary, audience,
+programme, topics, maturity, author/update metadata, sitemap policy,
+searchability, and future structured-data intent.
+
+Native HTML under `pages/` remains the durable semantic body content. The build
+checks that each page agrees with the registry on title, description,
+`data-page`, canonical URL policy, one `h1`, and public navigation.
+
+```text
+content/content-index.json
+ ↓ validation
+registered native HTML pages
+ ↓ static build
+routes + sitemap + site-manifest.json + future publishing indexes
+```
+
+The registry is designed to support later blog, paper/library, RSS, JSON-LD,
+related-content, and static full-text search gates without creating another
+manual route catalogue.
+
+## Working brand line
+
+The current master-brand line is:
+
+```text
+Correctness under concurrency.
+```
+
+It describes the programme's technical centre of gravity. It does not claim
+that every proposed Pinega technology is already implemented, verified, or
+commercially available.
+
+## Web architecture
```text
canonical Pinega tokens
@@ -13,46 +68,31 @@ Pinega CSS + Web Awesome theme adapter
↓
semantic Pinega components
↓
-multi-page website and documentation compositions
+registered static pages and documentation compositions
```
Web Awesome is intentionally not the canonical design system. Vendor tokens are
mapped from `design/tokens/strata.tokens.json`; research roles such as
`confirmed`, `inferred`, and `hypothesis` remain Pinega domain semantics.
-## Routes
-
-The build emits a static multi-page site:
-
-```text
-/ product homepage
-/docs/ documentation landing
-/docs/getting-started/ first documentation article
-/research/ research programme and shared semantic diagrams
-/component-lab/ design-system validation surface
-/404.html explicit not-found page
-```
-
-Source pages live under `pages/`. The component laboratory remains a separate
-source under `component-lab/` so production pages do not become test-fixture
-markup.
+Native HTML owns content and document semantics. CSS owns presentation,
+responsive adaptation, and visual state. JavaScript owns lifecycle and
+interaction enhancement. Public pages remain meaningful before Custom Elements
+register and without the licensed Web Awesome Pro project.
## Shared semantic diagrams
Canonical renderer-independent models live under `design/diagrams/models/`.
-The website build creates a temporary Node-only bundle from
-`src/diagrams/index.ts`, validates every model, lays it out, and replaces
-explicit `PINEGA_DIAGRAM` placeholders with complete accessible inline SVG
-figures.
+The build creates a temporary Node-only renderer bundle, validates and lays out
+each model, and replaces explicit `PINEGA_DIAGRAM` placeholders with complete
+accessible inline SVG figures.
-The temporary renderer bundle is deleted before the build finishes, so diagram
-layout code is not shipped to the browser. Each generated figure retains a
-caption, direct SVG title and description, keyboard-reachable viewport, text
-transcript, and a link to the canonical JSON model copied under
-`dist/diagrams/`.
+The temporary renderer is deleted before the build completes. Generated figures
+retain captions, direct SVG titles/descriptions, keyboard-reachable viewports,
+text transcripts, layout-profile identity, and links to canonical JSON. The
+same models feed the Typst/CeTZ publication renderer.
-The same JSON is consumed by `ydmp/templates/diagrams/shared-model.typ` for the
-Typst/CeTZ publication renderer.
+The Web IA milestone adds no new diagram family or promoted layout profile.
## Run locally with Nushell
@@ -60,6 +100,7 @@ Typst/CeTZ publication renderer.
cd web
^npm ci --ignore-scripts
^npm run build
+^npm run check:build
^npm run serve
```
@@ -69,9 +110,6 @@ Then open:
start 'http://127.0.0.1:4173'
```
-The development server resolves clean directory routes such as `/docs/` and
-returns the generated `404.html` with an HTTP 404 status for unknown paths.
-
## Deployment origin
Canonical URLs, `robots.txt`, and `sitemap.xml` are generated from
@@ -84,13 +122,12 @@ with-env { PINEGA_SITE_ORIGIN: 'https://www.example.com' } {
}
```
-The origin must contain only scheme and host, with no path, query, or fragment.
-
## Purchased Web Awesome Pro project
The public repository contains no project URL, license key, kit code, or Pro
asset. To activate the purchased project locally or in deployment, provide the
-private module URL at build time:
+private module URL at build time. Every public page retains a complete
+accessible fallback without Pro.
```nu
with-env {
@@ -101,24 +138,20 @@ with-env {
}
```
-The URL is injected as a `` value. Without
-Pro, every public page remains complete, readable, and testable.
-
## Implemented compositions
- `pinega-site-header`: light-DOM semantic header/navigation enhancement;
-- `pinega-hero`: responsive product narrative;
+- `pinega-hero`: responsive programme or technology narrative;
- `pinega-evidence`: YDMP provenance semantics with explicit text labels;
-- `pinega-code-example`: native code plus isolated Web Awesome copy action;
+- `pinega-code-example`: native code plus isolated copy enhancement;
- `pinega-benchmark`: canonical table, native SVG fallback, optional Pro chart;
-- `pinega-doc-search`: progressive client-side filtering over durable docs cards;
-- build-time semantic diagrams: linearizability histories, version chains, and
- object lifecycles with accessible SVG and textual projections.
+- `pinega-doc-search`: progressive filtering over durable documentation-topic
+ cards; it is not yet site-wide full-text search;
+- build-time semantic diagrams: histories, version chains, and lifecycles with
+ accessible SVG and textual projections.
## Validation
-Native checks:
-
```nu
^npm run tokens:check
^npm run typecheck
@@ -128,8 +161,8 @@ Native checks:
```
The complete browser matrix should use the version-matched Playwright container
-on unsupported Linux distributions. Browser tests cover the public routes,
-component laboratory, keyboard behavior, theme switching, docs search,
-semantic diagrams, not-found handling, horizontal overflow, metadata, local
-links, and automated accessibility. Chromium screenshots provide the visual-
-regression contract.
+on unsupported Linux distributions. Tests cover registered routes, route and
+fragment integrity, master-brand and maturity claims, public navigation,
+component-lab isolation, metadata generation, documentation filtering, browser
+behaviour, keyboard interaction, accessibility, responsive overflow, and
+committed visual baselines.
diff --git a/web/component-lab/index.html b/web/component-lab/index.html
index e32d236..1fb7e84 100644
--- a/web/component-lab/index.html
+++ b/web/component-lab/index.html
@@ -1,12 +1,12 @@
-
+
-
+
- Pinega Web Foundation v0.1
+ Pinega Strata component laboratory
@@ -16,7 +16,7 @@