norrietaylor · Jul 16, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,68 @@
+name: Bug report
+description: Something in minimal is broken or behaving unexpectedly
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: A clear description of the bug, including the full error output if there was any.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Minimal steps to reproduce the behavior — ideally the exact commands and a `minimal.toml` snippet.
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: Output of the version commands for the binaries involved.
+      placeholder: min version / mip --version
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: os-arch
+    attributes:
+      label: OS/arch
+      options:
+        - Linux amd64
+        - Linux arm64
+        - macOS arm64 (Apple Silicon)
+        - other
+    validations:
+      required: true
+  - type: dropdown
+    id: install-channel
+    attributes:
+      label: Install channel
+      options:
+        - stable
+        - unstable
+        - nightly
+        - built from source
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: Any relevant log output. Long logs are fine — this field is rendered as code automatically.
+      render: shell
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and discussion
+    url: https://github.com/gominimal/minimal/discussions
+    about: Ask questions and discuss ideas before filing an issue.
+  - name: Documentation
+    url: https://minimal-docs-staging.pages.dev/
+    about: Reference documentation for minimal.
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What problem are you trying to solve? What does the current behavior make hard or impossible?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What you would like to happen. Sketch the CLI/config surface if you have one in mind.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or workarounds you have considered, and why they fall short.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,17 @@
+<!-- PR title: use a Conventional Commit subject — `type(scope): summary`,
+     imperative, lower-case, no trailing period. The PR title becomes the
+     squash commit subject. See docs/commit-conventions.md. -->
+
+## Summary
+
+<!-- What changes, and why. Link related issues (`Refs: #123` / `Closes: #123`). -->
+
+## Testing
+
+<!-- What you ran (`cargo test`, `cargo clippy`, harness/e2e scripts, manual
+     steps) — paste the relevant output as evidence. -->
+
+## Checklist
+
+- [ ] Docs updated if behavior changed
+- [ ] `BREAKING CHANGE:` footer present if this is a breaking change
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -56,7 +56,11 @@ jobs:
                         - "!*.md"
                         - "!**/*.md"
                         - "!docs/**"
-                        - "!LICENSE"
+                        - "!LICENSE*"
+                        - "!NOTICE"
+                        - "!package.json"
+                        - "!package-lock.json"
+                        - "!.nvmrc"
 
     fmt:
         needs: [changes]

diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml
@@ -0,0 +1,178 @@
+name: docs-site
+
+# Docs-site lane. A THIN SCHEDULER: the build + link-check LOGIC lives in
+# scripts/docs-check.sh (and the `just docs-check` recipe), per the CI contract
+# in CONTRIBUTING.md / docs/ci-strategy.md — this workflow only gates events,
+# installs the toolchain (Node, lychee), invokes the script, and uploads the
+# rendered site. The script builds the VitePress site (`npm run docs:build`),
+# fails on site-absolute links under docs/reference/ (those pages are mirrored
+# into gominimal/webapp, where `](/...` resolves against a different base, and
+# they are equally broken when read on GitHub), and offline-checks internal
+# links with lychee. This workflow uploads the rendered site
+# (docs/.vitepress/dist) as an artifact; a weekly scheduled job runs the
+# script's ONLINE lychee sweep (advisory only); a Pages deploy job is fully
+# drafted but disabled until launch.
+#
+# NOT a required check yet. Making `docs-site-success` required is a
+# branch-protection change (main ruleset edit) AND touches release.yml's
+# verify-ci expectations — its `required=` list of lane aggregators would
+# need `docs-site-success` appended. Both are owner decisions.
+#
+# ALWAYS-TRIGGERED, path-scoped INSIDE the workflow (the `changes` job), so
+# the `if: always()` aggregator can join the required checks later without a
+# deadlock. Do NOT add trigger-level `paths:` — a path-skipped required
+# context stays "Expected" forever and wedges the PR (see ci.yml).
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+  schedule:
+    # Weekly ONLINE link sweep only — every other job no-ops on schedule.
+    # 05:00 UTC Monday, offset from nightly.yml (10:00 daily) and
+    # nightly-tests.yml (06:00 daily).
+    - cron: "0 5 * * 1"
+
+# Cancel superseded runs on a branch; never cancel a run on main.
+concurrency:
+  group: docs-site-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: read
+  # dorny/paths-filter reads the PR file list on pull_request events.
+  pull-requests: read
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Detect docs-site changes
+        id: filter
+        # v3.0.2, SHA-pinned. Runs ONLY on pull_request, where dorny reads
+        # the PR file list via the API (a push would need a local diff our
+        # shallow, credential-free checkout cannot provide) — and pushes to
+        # main / dispatches run everything regardless. POSITIVE filter,
+        # unlike ci.yml's everything-but-docs negation: this lane cares only
+        # about the site sources and the Node toolchain pins.
+        if: github.event_name == 'pull_request'
+        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706
+        with:
+          filters: |
+            docs:
+              - "docs/**"
+              - "package.json"
+              - "package-lock.json"
+              - ".nvmrc"
+              # Lane idiom: a workflow-only PR must still exercise its lane.
+              - ".github/workflows/docs-site.yml"
+
+  docs-build:
+    needs: [changes]
+    # Never on schedule (that trigger exists only for link-sweep); otherwise
+    # the standard lane gate: run unless a pull_request touched no docs path.
+    if: github.event_name != 'schedule' && (github.event_name != 'pull_request' || needs.changes.outputs.docs == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v5
+        with:
+          node-ver
106FC
sion-file: .nvmrc
+          cache: npm
+      # TODO: enable once the gen-cli-docs xtask exists — it regenerates the
+      # docs/reference/cli-*.md pages from the clap definitions and fails on
+      # any diff, so the committed pages can never drift from --help output.
+      # Needs a Rust toolchain when enabled (add
+      # `- uses: ./.github/actions/setup-rust` above it).
+      # - name: CLI reference pages are current
+      #   run: cargo xtask gen-cli-docs --check
+      - name: Build site
+        # npm ci + `npm run docs:build`; the logic is repo-owned in the script.
+        run: ./scripts/docs-check.sh build
+      # Tool install is a scheduler concern (kept in the workflow); the offline
+      # link-check LOGIC lives in the script the next step calls.
+      - name: Install lychee
+        uses: taiki-e/install-action@v2
+        with:
+          tool: lychee
+      - name: Check links (site-absolute guard + offline lychee)
+        run: ./scripts/docs-check.sh links
+      - name: Upload rendered site
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-site-dist
+          path: docs/.vitepress/dist
+
+  link-sweep:
+    # Weekly ONLINE sweep of external URLs. Advisory: dead third-party links
+    # and rate limits must not redden the repo, hence continue-on-error at
+    # the job level and no edge into the aggregator; failures surface in the
+    # Actions log for a human to triage.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Install lychee
+        uses: taiki-e/install-action@v2
+        with:
+          tool: lychee
+      - name: Online link check
+        run: ./scripts/docs-check.sh online-links
+
+  docs-deploy:
+    needs: [docs-build]
+    # Fully drafted but DISABLED. Enabling is a launch decision: it needs the
+    # repository's Pages source set to "GitHub Actions" and the public site
+    # URL settled. To enable, replace the `if: false` line below with:
+    #   if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    if: false # enable at launch
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: docs-site-dist
+          path: dist
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  # Single stable status for (eventual) branch protection: green when every
+  # gating job succeeded OR was skipped (docs-untouched PRs, the disabled
+  # deploy); red only on failure/cancellation. Mirrors ci.yml's ci-success
+  # idiom. link-sweep is deliberately NOT in `needs`: it is advisory and
+  # runs on a schedule, so it must never colour this check.
+  docs-site-success:
+    if: always()
+    needs: [changes, docs-build, docs-deploy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Verify all gating jobs succeeded or were skipped
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1
+      - run: echo "All docs-site gates passed"