dominicusin · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
@@ -1,11 +1,12 @@
 name: 🧪 R&D Tests
 
-# Isolated R&D test gate (TASK-C2 / T89). Runs the experimental-plane suites
-# (src/ jest + contracts/dao hardhat) separately from the production Hugo build
-# so a flaky R&D test cannot block the GitHub Pages deploy. Triggered on any
-# change touching the R&D surface. Not a required status check for merge
-# (the required checks are "test" + "build" in hugo.yml), but it surfaces R&D
-# regressions on every relevant push/PR.
+# STATUS: disabled manually in GitHub Actions after the DAO test job failed on
+# main (last updated 2026-08-25). Do not describe this workflow as an active
+# check. Re-enable it after repairing and verifying the DAO test suite.
+#
+# When enabled, this isolates the experimental-plane suites (src/ Jest and
+# contracts/dao Hardhat) from the production Hugo build, so an R&D failure does
+# not block the Pages deploy. The job is not a required status check for merge.
 
 on:
   push:

@@ -6,7 +6,8 @@
 > production SSG and stays — no migration to Astro/Jekyll. `docs/SSG_MIGRATION_PLAN.md`
 > is **superseded** (its original plan was based on a stale snapshot); `docs/STRATEGIC_PLAN_2026-2027.md`
 > carries a stale baseline — see its reconciliation header. Source of truth for
-> current state: this file + `ROADMAP.md` + `AUDIT-2026-08.md`.
+> current state: this file + `docs/ROADMAP_STATUS.md` +
+> `docs/architecture/AUDIT-2026-08.md`.
 
 ## Overview
 
@@ -113,6 +114,7 @@ in CI, so the version there is authoritative.
 | Lines | 76.57% |
 
 This is the **official baseline** (not the aspirational 85% target, which
-requires an E2E/Playwright layer — tracked in `ROADMAP.md` / `AUDIT-2026-08.md`,
-not in the (stale-baseline) `STRATEGIC_PLAN_2026-2027.md`.
+requires an E2E/Playwright layer — tracked in `docs/ROADMAP_STATUS.md` /
+`docs/architecture/AUDIT-2026-08.md`, not in the (stale-baseline)
+`STRATEGIC_PLAN_2026-2027.md`.
 Do not regress below these numbers on the `src/` plane without adding tests.
@@ -1,121 +1,41 @@
-# Contributing to dominicusin.github.io
+# Contributing
 
-## Quick Start
+This repository publishes a Hugo site and retains a separate engineering archive. See the [README](README.md) for the project map and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the build boundary.
 
-```bash
-# 1. Clone
-git clone https://github.com/dominicusin/dominicusin.github.io.git
-cd dominicusin.github.io
+## Site content
 
-# 2. Install deps
-npm install
+1. Add articles under `content/blog/` and pages under the appropriate `content/` section.
+2. Keep front matter aligned with `schema/post-metadata.schema.json` and preserve old URLs with Hugo aliases when renaming content.
+3. Validate a new article with `node scripts/validate-frontmatter.cjs content/blog/<file>.md`.
+4. Follow the author checklist in [docs/PUBLISHING.md](docs/PUBLISHING.md).
 
-# 3. Build
-npm run build
+For a local site preview, install Node.js 24 and Hugo Extended 0.164.0, then initialize the theme and generators:
 
-# 4. Test
-npm test
-
-# 5. Serve locally
-npm run start
-```
-
-## Project Structure
-
-```
-├── assets/
-│   ├── css/
-│   │   ├── neo.css          # Neo design system (main CSS)
-│   │   └── critical/        # Above-fold critical CSS
-│   └── js/
-│       └── custom.js        # All client-side JS
-├── content/                 # Hugo content (blog, repos, gists, awesome)
-│   ├── blog/
-│   ├── repositories/
-│   ├── gists/
-│   └── awesome/
-├── data/                    # Hugo data files (JSON)
-├── layouts/
-│   ├── _default/            # Default templates
-│   ├── partials/            # Reusable partials
-│   │   ├── neo-head.html    # <head> with SEO + performance
-│   │   ├── neo-store.html   # Centralized localStorage
-│   │   ├── content-graph.html # Related posts + tags
-│   │   └── neo-subscribe.html # Newsletter + share
-│   ├── shortcodes/          # Hugo shortcodes
-│   └── analytics/           # Dashboard templates
-├── static/                  # Static files (served as-is)
-│   ├── sw.js                # Service Worker
-│   ├── manifest.webmanifest # PWA manifest
-│   └── .well-known/security.txt
-├── scripts/                 # Build scripts
-└── tests/                   # Test suites
-    ├── unit/                # Unit tests
-    ├── a11y/                # Accessibility
-    └── e2e/                 # End-to-end
+```sh
+git submodule update --init themes/blowfish
+npm ci --prefix scripts
+node scripts/sync-github.cjs
+node scripts/build-knowledge-graph.cjs
+node scripts/build-ontology-feed.cjs
+node scripts/build-crosslinks.cjs
+node scripts/build-awesome.cjs
+hugo server -D
 ```
 
-## Development Workflow
-
-### Branch Naming
-- `feat/waveXX-feature-name` — new features
-- `fix/issue-description` — bug fixes
-- `chore/task-name` — maintenance
-
-### Pull Request Process
-1. Create feature branch from `main`
-2. Make changes, verify locally: `npm run build && npm test`
-3. Push and create PR
-4. Quality CI must pass (build → validate → test → link-check)
-5. Merge via `gh pr merge --squash --admin`
+## Engineering archive
 
-### Code Style
-- **CSS**: Use Neo design tokens (`--bg`, `--text`, `--accent`)
-- **JS**: Use IIFE pattern, avoid global scope pollution
-- **HTML**: Use semantic elements, ARIA labels
+`src/` and `contracts/dao/` are retained research projects and are not included in the published site. Install the root Node dependencies to work on them:
 
-## Testing
-
-```bash
-# All tests
+```sh
+npm ci
+npm run lint
 npm test
-
-# Unit tests only
-npx jest tests/unit
-
-# With coverage
-npm run test:coverage
+npx hardhat test
 ```
 
-## Design System
-
-### Themes
-Switch via `data-theme` attribute on `<html>`:
-- `dark` (default)
-- `light`
-- `solar`
-- `mono`
-- `dracula`
-
-### Accents
-Switch via `data-accent` attribute:
-- `teal` (default)
-- `violet`
-- `amber`
-- `emerald`
-- `rose`
-
-### Key Classes
-- `.neo-card` — content cards
-- `.neo-row` — list items
-- `.neo-post` — article wrapper
-- `.neo-wrap` — content container
-- `.neo-sec-head` — section header
-
-## Architecture Decisions
+## Pull requests
 
-1. **No backend** — static site on GitHub Pages
-2. **localStorage** — centralized in `neoStore` (neo-store-v1)
-3. **Critical CSS** — inline above-fold, async rest
-4. **Search** — build-time index, client-side fuzzy match
-5. **Analytics** — local only, no external tracking
+- Open changes against `main` and describe the user-visible or maintenance outcome.
+- The required **Quality CI** check builds Hugo and checks content metadata, lint, and internal links. Playwright and security workflows run separately.
+- The R&D test workflow is currently disabled because its DAO test job fails on `main`; archive test commands remain available locally.
+- Keep generated build output, dependency folders, and Hugo caches out of commits.
@@ -1,122 +1,74 @@
-# dominicusin.github.io — Engineering Blog (Hugo + Blowfish)
+# dominicusin.github.io
 
-[![Deploy](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml/badge.svg)](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml)
-[![Tests](https://img.shields.io/badge/tests-277%20jest%20%2B%209%20hardhat-brightgreen)](tests/)
+[![Pages](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml/badge.svg)](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> Static engineering blog built with **Hugo** + the **Blowfish** theme, deployed to GitHub Pages.
-> Migrated from the legacy Jekyll + esbuild stack (see `docs/SSG_MIGRATION_PLAN.md`).
-
-Domini's personal engineering blog: industrial engineering, systems engineering, and data science,
-plus decentralized-web / DAO notes.
-
-## 🚀 Architecture (two planes)
-
-This repository deliberately separates **publishing** from **engineering tooling**:
-
-- **Publishing Plane** — the website.
-  - Generator: Hugo (extended) + Blowfish theme (git submodule at `themes/blowfish`).
-  - Content: `content/` (blog posts in `content/blog/`, `content/people/`, `content/domini/`).
-  - Config: `config/_default/` (`hugo.toml`, `config.toml`, `params` inline, `menus.*.toml`, `languages.toml`).
-  - Comments: [giscus](https://giscus.app) (GitHub Discussions backend, category "Announcements").
-  - Subscription: Buttondown form (`layouts/partials/subscription.html`).
-  - i18n: `i18n/{ru,en}.yaml` (ru default, en secondary).
-  - Build/deploy: `.github/workflows/hugo.yml` → GitHub Pages (single publisher).
-- **Engineering Plane** — smart-contract / DAO tooling (kept separate, NOT deployed to the site).
-  - `contracts/dao/` — Solidity sources.
-  - `tests/hardhat/` — Hardhat tests (`npx hardhat test`, 9 passing).
-  - `scripts/` — content-contract + knowledge-graph generation.
-  - `src/` — v4.0 frontend modules (CRDT/P2P/DAO/BCI adapters). Retained for the engineering
-    substrate; not bundled into the static site (Hugo ignores `src/`).
-
-See [`docs/adr/0002-two-plane-architecture.md`](docs/adr/0002-two-plane-architecture.md) for the
-formal two-plane boundary, integration points, and DAO lifecycle.
-
-## 🛠 Local development
-
-```bash
-# 1. Install Hugo (extended) — e.g. via Go:
-#    CGO_ENABLED=0 go install github.com/gohugoio/hugo@v0.164.0
-# 2. Init the theme submodule:
-git submodule update --init --recursive
-# 3. Run the dev server (drafts included):
+Personal engineering blog and knowledge library: [dominicusin.github.io](https://dominicusin.github.io/).
+The public site is built with Hugo and the Blowfish theme, with Russian as its primary language.
+
+## How the project fits together
+
+The repository has two clear parts:
+
+- **Website:** Hugo content, templates, theme, and generated site data. This is the only part published to GitHub Pages.
+- **Engineering archive:** `src/`, `contracts/dao/`, and their tests. These are retained experiments; they are not shipped with the site.
+
+The architecture boundary and its rationale are recorded in
+[`docs/adr/0002-two-plane-architecture.md`](docs/adr/0002-two-plane-architecture.md).
+The current implementation overview is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Build and preview the site
+
+Requirements: Node.js 24, Hugo Extended 0.164.0, and the Blowfish theme submodule.
+
+```sh
+git submodule update --init themes/blowfish
+npm ci --prefix scripts
+node scripts/sync-github.cjs
+node scripts/build-knowledge-graph.cjs
+node scripts/build-ontology-feed.cjs
+node scripts/build-crosslinks.cjs
+node scripts/build-awesome.cjs
 hugo server -D
-# 4. Production build:
-hugo --gc --minify
 ```
 
-The site is served from `public/` after a build. `public/` and `resources/` are git-ignored.
-
-## 📦 Content model
-
-- Posts live in `content/blog/` as `YYYY-MM-DD-slug.md`. Frontmatter is normalized
-  (title, date ISO-8601, categories, tags, authors, draft, slug).
-- Legacy permalinks are preserved via Hugo `aliases` (e.g. `/2015/11/19/first.html` → `/2015/11/19/first/`).
-- The `content/posts` → `content/blog` rename keeps post URLs intact; `/posts/` now aliases `/blog/`.
-- Every **new** post (added in a PR) is validated as a **hard gate** against
-  `schema/post-metadata.schema.json` in CI (`scripts/ci-content-contract.cjs`):
-  an invalid new post **blocks the deploy**. Modified legacy posts (e.g. 2015
-  posts lacking tags/author) are report-only and do not block.
-- Author hint: run `node scripts/ci-content-contract.cjs` locally before push to
-  self-check; `node scripts/validate-frontmatter.cjs content/blog/<file>` validates a single post.
-
-## 🔧 Key files
-
-| Path | Purpose |
-|------|---------|
-| `config/_default/hugo.toml` | Site + Blowfish params, permalinks, outputs, giscus, subscription URL |
-| `config/_default/config.toml` | `theme = "blowfish"` declaration |
-| `themes/blowfish` | Theme submodule (v2.105.0) |
-| `content/` | All site content |
-| `layouts/partials/comments.html` | giscus + subscription injection |
-| `i18n/` | ru/en translations |
-| `contracts/dao/`, `tests/hardhat/` | DAO engineering plane |
-| `.github/workflows/hugo.yml` | The only GitHub Pages publisher |
-
-## ⚙️ CI/CD (single publisher model)
-
-Only `.github/workflows/hugo.yml` deploys to GitHub Pages. Other workflows are
-quality/support and never flip the Pages source.
-
-| Workflow | Purpose | Deploys? |
-|----------|---------|----------|
-| `hugo.yml` | Build + **content-contract hard gate (new posts)** + deploy to Pages | ✅ yes |
-| `hugo-build-check.yml` | Build-only sanity check | ❌ |
-| `security.yml` | Node audit + Trivy + Semgrep (weekly) | ❌ |
-| `performance.yml` | Lighthouse audit against live Pages URL | ❌ |
-| `dependency-update.yml` | Dependabot-driven bumps | ❌ |
-| `link-repair.yml` | Scheduled broken-link check | ❌ |
-| `deploy-dao.yml` | `test` job (Hardhat, no secrets) + guarded `deploy` (needs secrets) | ❌ (separate track) |
-| `vr-export.yml` | Build-only VR artifact (no Pages flip) | ❌ |
-| `sync_gists.yml`, `analytics.yml`, `fediverse-notify.yml` | Post-deploy integrations | ❌ |
-| `deploy-ipfs.yml` | **DISABLED** (legacy Jekyll + compromised Pinata) | ❌ |
-
-> The legacy Jekyll CI (`ci.yml`, `jekyll.yml`, `ci-cd.yml`) was removed in
-> Phase 7. Do not reintroduce `bundle exec jekyll build` — the site is Hugo-only.
-
-## 🧠 Knowledge Hub (Engineering Knowledge Platform)
-
-The site is more than a blog: it is a navigable knowledge base.
-
-- **Knowledge Graph** (`/knowledge-graph/`) — interactive concept/post explorer
-  backed by `/data/knowledge-graph.json` (JSON-LD, generated each build). Noscript
-  fallback via `/categories/` + `/tags/`.
-- **Community** (`/community/`) — giscus (GitHub Discussions) comments + Buttondown
-  subscription, with discussion norms and a privacy note.
-- **Editorial strategy**: `docs/EDITORIAL_STRATEGY.md` (content directions, taxonomy,
-  people/domini rules, author checklist).
-- **DAO track**: `docs/DAO_ROADMAP.md` (contracts, test/deploy, threat model).
-- **Architecture**: `docs/adr/0002-two-plane-architecture.md` (Publishing vs Engineering).
-- **Content contract**: `docs/CONTENT_CONTRACT.md` (new posts are a hard gate).
-
-## 🧹 Legacy (removed)
-
-The legacy Jekyll + esbuild stack (`_config.yml`, `Gemfile`, `_layouts/`, `_includes/`,
-`_sass/`, `_posts/`, `_site/`, `js/`, `build.js`, `build-jekyll.rb`) and the Jekyll CI workflows
-(`ci.yml`, `jekyll.yml`, `ci-cd.yml`) were **removed** in Phase 7 (rollback point tagged
-`pre-phase7-legacy`). The Hugo site is the sole publisher. `src/` (DAO/CRDT modules) and
-`contracts/dao/` are retained as the engineering plane.
-
-## 📄 License
-
-MIT — see `LICENSE`.
+Open the local URL printed by Hugo. To create the production output in `public/`:
+
+```sh
+hugo --gc --minify --baseURL "https://dominicusin.github.io/"
+```
+
+The deploy workflow runs the data generators and Hugo build in this order, then publishes the `public/` artifact to GitHub Pages. Pushes to `main` and the scheduled repository sync both use this workflow. The `quality.yml` workflow checks pull requests and never deploys.
+
+## Where to work
+
+| Area | Source of truth |
+| --- | --- |
+| Posts and pages | `content/` |
+| Site settings and navigation | `config/_default/` |
+| Theme overrides | `layouts/`, `assets/`, `static/`, `i18n/` |
+| Generated site data | `data/`, `static/data/`, generated by `scripts/` |
+| Content rules | `schema/post-metadata.schema.json`, `docs/CONTENT_CONTRACT.md` |
+| Publishing and operations | `docs/PUBLISHING.md`, `docs/OPERATIONS.md` |
+| Frozen engineering archive | `src/`, `contracts/dao/`, `tests/` |
+
+New articles belong in `content/blog/`. Keep front matter aligned with the content schema; CI checks new articles before they can be published. Use Hugo aliases when changing a page URL so existing links continue to work.
+
+## Project checks
+
+The required pull request gate is **Quality CI**. It installs the root Node dependencies, builds Hugo, checks content and internal links, and runs the repository lint step. The Playwright workflow runs separately. The R&D test workflow is currently disabled in GitHub Actions because its DAO test job fails on `main`; its suites are not part of the required pull request gate.
+
+Useful local commands:
+
+```sh
+npm ci
+npm run lint
+npm test
+npx hardhat test
+```
+
+These commands are available for local work on the engineering archive. The site build uses the nested tooling dependencies installed with `npm ci --prefix scripts`.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).