docs(journeydoc): bootstrap capture-driven user documentation

[rubenvdlinde]

Summary

Stands up a Docusaurus documentation site for OpenBuilt and drops the journeydoc (ADR-030) capture-driven tutorials scaffold. Adapted from the working pipelinq/docs/ reference + the journeydoc templates in hydra/templates/journeydoc/.

What landed

Docusaurus site (docs/)

• docusaurus.config.js — built on @conduction/docusaurus-preset; title: OpenBuilt, url: https://openbuilt.conduction.nl, baseUrl: /, organizationName: ConductionNL, projectName: openbuilt, editUrl → ConductionNL/openbuilt/tree/main/docs/. i18n.locales: ['en'] only (Dutch omitted until translated markdown exists — ADR-030 comment explains why). onBrokenMarkdownImages: 'warn' so the build survives a fresh checkout without screenshots.
• package.json (name: openbuilt-docs), package-lock.json (name field updated), sidebars.js (autogenerated sidebar).
• src/pages/index.js — landing page using the brand <DetailHero> + <WidgetShelf> with OpenBuilt-specific copy and three mock widget panels (template gallery, schema designer, version snapshots).
• src/components/HomepageFeatures/index.js, src/css/custom.css, module CSS — adapted.
• intro.md — OpenBuilt overview landing doc.
• static/CNAME = openbuilt.conduction.nl; static/img/logo.svg; static/screenshots/tutorials/{user,admin}/.gitkeep.
• Existing docs/integrator-guide.md, docs/openbuilt-rbac.md, docs/openbuilt-runtime.md kept as-is (picked up by the autogenerated sidebar).

Journeydoc tutorial skeletons (docs/tutorials/)

• _category_.json for the Tutorials root + user/ + admin/ tracks.
• User track (8): 01-first-launch, 02-create-from-template, 03-design-schema, 04-design-page, 05-connect-data, 06-preview-app, 07-version-snapshots, 08-export-app.
• Admin track (3): 01-rbac, 02-template-catalogue, 03-admin-settings.
• Each page from tutorial-page.md.template with {{POSITION}} / {{TITLE}} / {{DESCRIPTION}} pre-filled and body sections as {{TODO: …}} for the human author / /journeydoc-add-story.

Capture spec (tests/e2e/docs-screenshots.spec.ts)

• New file with the shoot() helper and one empty test('UN <slug>', …) per story (11 total) — each a /* TODO: see /journeydoc-add-story */ stub.

playwright.config.ts splice

• Added the opt-in docs-capture project (testMatch: /docs-screenshots\.spec\.ts$/, 1280×800, 90 s timeout).
• Added testIgnore: ['**/docs-screenshots.spec.ts'] to the existing chromium project so PR pipelines don't reshoot.
• All existing playwright projects/specs untouched (application-editor, builder-host, page-designer, schema-designer, template-gallery, version-rollback, rbac-403, export-zip, manifest-endpoint, bootstrap-openbuilt).

CI wiring (.github/workflows/documentation.yml)

• cname: switched from openbuilt.app → openbuilt.conduction.nl (ADR-030 canonical domain).
• Triggers extended to [development, documentation] (was documentation only).

Notes / caveats

• The Docusaurus config is a best-effort adaptation of the pipelinq pattern — it depends on @conduction/docusaurus-preset which isn't installed in this workspace, so the site build was not verified locally. Worth a npm ci --legacy-peer-deps && npm run build in docs/ before merge.
• package-lock.json is pipelinq's lock with the name field changed (deps are identical). Regenerate with npm install in docs/ if a clean lock is preferred.
• The capture-spec test() blocks are intentionally empty stubs — they'll fail/skip until filled via /journeydoc-add-story + /journeydoc-instrument.
• Existing docs/*.md reference pages contain relative links like ../openspec/changes/ that will surface as broken-link warnings; onBrokenLinks: 'warn' (preset default) keeps the build green.

Next steps (post-merge)

1. Fill the TODOs in docs/tutorials/{user,admin}/*.md — use /journeydoc-add-story <track> "<title>".
2. Run /journeydoc-instrument <vue-file> on capture-relevant components to add stable data-testids.
3. npx playwright test --project docs-capture to populate screenshots.
4. Configure DNS for openbuilt.conduction.nl → conductionnl.github.io and enable HTTPS in GitHub Pages settings.

[github-actions]

Quality Report — ConductionNL/openbuilt @ 30347ac

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 100/100
npm			✅	✅ 432/432
PHPUnit					✅
Newman					❌
Playwright					⏭️

Coverage: 0% (0/19 statements)

---

Quality workflow — 2026-05-12 14:01 UTC

Download the full PDF report from the workflow artifacts.