docs: establish the Weave platform knowledge base

.github/CODEOWNERS

@@ -1,13 +1 @@
-# See for instructions on this file <https://help.github.com/articles/about-codeowners/>
-
-# These owners will be the default owners for everything in
-# the repo. Unless a later match takes precedence,
-# @global-owner1 and @global-owner2 will be requested for
-# review when someone opens a pull request.
-
 * @ShocOne
-
-.azuredevops/** @ShocOne
-.github/** @ShocOne
-.pipelines/** @ShocOne
-workload/** @ShocOne

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,49 +1,14 @@
-# Pull Request Description
+Describe the knowledge change and who it helps.
 
-## Summary
-[Provide a brief description of the changes in this PR]
+## Evidence
 
-### Issue Reference
-Fixes #[Issue Number]
+- Source commits and inspected implementation paths:
+- Contract or runtime checks performed:
+- Compatibility limits or unresolved claims:
 
-### Motivation and Context
-- Why is this change needed?
-- What problem does it solve?
-- If it fixes an open issue, please link to the issue here
+## Validation
 
-### Dependencies
-- List any dependencies that are required for this change
-- Include any configuration changes needed
-- Note any version updates required
-
-## Type of Change
-Please mark the relevant option with an `x`:
-- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
-- [ ] ✨ New feature (non-breaking change which adds functionality)
-- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] 📝 Documentation update (Wiki/README/Code comments)
-- [ ] ♻️ Refactor (code improvement without functional changes)
-- [ ] 🎨 Style update (formatting, renaming)
-- [ ] 🔧 Configuration change
-- [ ] 📦 Dependency update
-
-## Testing
-- [ ] I have added unit tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] I have tested this code in the following browsers/environments: [list environments]
-
-## Quality Checklist
-- [ ] I have reviewed my own code before requesting review
-- [ ] I have verified there are no other open Pull Requests for the same update/change
-- [ ] All CI/CD pipelines pass without errors or warnings
-- [ ] My code follows the established style guidelines of this project
-- [ ] My comments are used only when necessary, ideally where the codes purpose is not self explanatory (eg: necessary magic numbers)
-- [ ] I have added necessary documentation (if appropriate)
-- [ ] I have made corresponding changes to the README and other relevant documentation
-- [ ] My changes generate no new warnings
-
-## Screenshots/Recordings (if appropriate)
-[Add screenshots or recordings that demonstrate the changes]
-
-## Additional Notes
-[Add any additional information that might be helpful for reviewers]
+- [ ] Content, evidence, build and link checks pass.
+- [ ] Diagrams pass showcase validation and browser evidence.
+- [ ] An image-capable reviewer inspected both diagram themes.
+- [ ] Any export from a private source has publication review.

.github/dependabot.yml

@@ -1,29 +1,13 @@
-# See GitHub's documentation for more information on this file:
-# https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates
 version: 2
 updates:
-  # Maintain dependencies for GitHub Actions
-  - package-ecosystem: "github-actions"
-    directory: "/"
+  - package-ecosystem: npm
+    directory: /
     schedule:
-      # Check for updates to GitHub Actions every week
-      interval: "weekly"
-    commit-message:
-      # Prefix all commit messages with "chore(deps): "
-      # This follows conventional commits and works with release-please
-      prefix: "chore(deps)"
-      prefix-development: "chore(deps-dev)"
-      include: "scope"
-
-  # Maintain dependencies for Go modules
-  - package-ecosystem: "gomod"
-    directory: "/"
+      interval: weekly
+    groups:
+      docusaurus:
+        patterns: ['@docusaurus/*']
+  - package-ecosystem: github-actions
+    directory: /
     schedule:
-      # Check for updates to Go modules every week
-      interval: "weekly"
-    commit-message:
-      # Prefix all commit messages with "chore(deps): "
-      # This follows conventional commits and works with release-please
-      prefix: "chore(deps)"
-      prefix-development: "chore(deps-dev)"
-      include: "scope"
+      interval: weekly

.github/workflows/deploy.yml

@@ -0,0 +1,79 @@
+name: Publish documentation
+on:
+  workflow_dispatch:
+    inputs:
+      build_run:
+        description: 'Successful main Documentation quality gate run ID (internal owner release)'
+        required: true
+        type: string
+  workflow_run:
+    workflows: [Documentation quality gate]
+    branches: [main]
+    types: [completed]
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: docs-production
+  cancel-in-progress: false
+jobs:
+  select:
+    if: vars.DOCS_DEPLOY_ENABLED == 'true' && ((github.event_name == 'workflow_run' && vars.DOCS_AUDIENCE != 'internal' && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' && github.event.workflow_run.head_repository.full_name == github.repository) || (github.event_name == 'workflow_dispatch' && vars.DOCS_AUDIENCE == 'internal' && github.ref == 'refs/heads/main' && github.actor == vars.DOCS_RELEASE_OWNER))
+    runs-on: ubuntu-latest
+    outputs:
+      commit: ${{ steps.build.outputs.commit }}
+      run: ${{ steps.build.outputs.run }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: main
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .node-version
+      - id: build
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DOCS_BUILD_RUN: ${{ github.event.workflow_run.id || inputs.build_run }}
+        run: node scripts/select-build.mjs
+  publish:
+    needs: select
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.select.outputs.commit }}
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .node-version
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: documentation-site
+          path: site/build
+          run-id: ${{ needs.select.outputs.run }}
+          github-token: ${{ github.token }}
+      - name: Bind deployment to verified build
+        env:
+          DOCS_COMMIT: ${{ needs.select.outputs.commit }}
+          DOCS_RUN: ${{ needs.select.outputs.run }}
+        run: node scripts/deployment-manifest.mjs
+      - name: Deploy production
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          DOCS_PAGES_PROJECT: ${{ vars.DOCS_PAGES_PROJECT }}
+          DOCS_COMMIT: ${{ needs.select.outputs.commit }}
+        run: npx wrangler pages deploy site/build --project-name "$DOCS_PAGES_PROJECT" --branch main --commit-hash "$DOCS_COMMIT"
+      - name: Verify public deployment or internal Access boundary
+        env:
+          DOCS_CANONICAL_URL: ${{ vars.DOCS_CANONICAL_URL }}
+          DOCS_AUDIENCE: ${{ vars.DOCS_AUDIENCE || 'public' }}
+          DOCS_PAGES_PROJECT: ${{ vars.DOCS_PAGES_PROJECT }}
+          DOCS_COMMIT: ${{ needs.select.outputs.commit }}
+          CF_ACCESS_CLIENT_ID: ${{ secrets.CF_ACCESS_CLIENT_ID }}
+          CF_ACCESS_CLIENT_SECRET: ${{ secrets.CF_ACCESS_CLIENT_SECRET }}
+        run: node scripts/smoke-deployment.mjs

.github/workflows/docs-kit-release.yml

@@ -0,0 +1,24 @@
+name: Release shared documentation kit
+on:
+  push:
+    tags: ['docs-kit-v*']
+permissions:
+  contents: write
+jobs:
+  release:
+    if: github.repository == 'weaveplatform/weaveplatform.run'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .node-version
+      - name: Check tag and package version match
+        run: node -e 'const p = require("./packages/docs-kit/package.json"); if (process.env.GITHUB_REF_NAME !== "docs-kit-v" + p.version) process.exit(1)'
+      - run: npm pack --workspace packages/docs-kit
+      - name: Publish immutable kit archive and checksum
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          sha256sum weaveplatform-docs-kit-*.tgz > docs-kit.sha256
+          gh release create "$GITHUB_REF_NAME" weaveplatform-docs-kit-*.tgz docs-kit.sha256 --title "$GITHUB_REF_NAME" --notes 'Shared documentation theme, components and page schema. Pin the archive checksum before upgrading the private site.'