knowledge_board.yml

name: Dashboard

# Publishes the PyAutoMemory Dashboard — the management view of the Memory's papers
# and wikis (scripts/board.py, the Heart/Hands dashboard pattern):
#   * the GitHub Pages page (one-tap 📋 work prompts for a phone),
#   * badge.json (the shields endpoint the README badge reads),
#   * state.json (the organ-cockpit feed, Brain contract v1 — validated below),
#   * the one-line README strip between the memory:begin/end markers.
#
# Contents-level only: titles and counts, never claim text. Nothing is
# committed — validate_structure.py bans .html and gates the root allowlist,
# so every surface is rendered fresh here.

on:
  push:
    branches: [main]
    paths:
      - "wiki/**"
      - "bibliography/**"
      - "reading-queue.md"
      - "arxiv-inbox.md"
      - "arxiv-interests.md"
      - "index.md"
      - "scripts/board.py"
      - "scripts/inbox_actions.py"
      - "scripts/interests_actions.py"
  schedule:
    - cron: "45 5 * * 1"
  workflow_dispatch:

# contents: write → the README strip self-commit; pages/id-token → publish;
# issues: write → create the action labels the rendered buttons reference
# (see "Ensure the per-paper action labels exist" below).
permissions:
  contents: write
  issues: write
  pages: write
  id-token: write

concurrency:
  group: knowledge-board-pages
  cancel-in-progress: false

jobs:
  board:
    name: Render + publish the dashboard
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # Full history: the catch-up banner dates the last ingest from the
      # commits that added bib entries (scripts/catch_up.py); a shallow clone
      # has none of them.
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # A prefilled `…/issues/new?…&labels=x` URL silently drops `x` when the
      # label does not exist in the repo, and queue_actions.yml gates on the
      # label — so a missing label makes a tapped button look like it worked
      # and then do nothing. The board renders those buttons, so the board
      # guarantees their labels. `gh api` rather than `gh label create`: it
      # works on any gh version, and 422 (already exists) is the normal case.
      - name: Ensure the per-paper action labels exist
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -u
          ensure() {
            gh api "repos/${GITHUB_REPOSITORY}/labels" \
              -f "name=$1" -f "color=$2" -f "description=$3" \
              >/dev/null 2>&1 && echo "created $1" || echo "exists $1"
          }
          ensure queue-read    "0e8a16" "reading queue: mark this paper read"
          ensure queue-cite    "1d76db" "reading queue: file a minimal citeable entry"
          ensure queue-intake  "5319e7" "reading queue: file this paper fully into the wiki"
          ensure queue-add     "fbca04" "arXiv inbox: move this paper into the reading queue"
          ensure queue-dismiss "d4c5f9" "arXiv inbox: drop this suggestion"
          ensure interests-add     "fbca04" "arXiv interests: move this paper into the reading queue"
          ensure interests-dismiss "d4c5f9" "arXiv interests: drop this suggestion"
          ensure interests-clear   "b60205" "arXiv interests: clear a whole day's batch"

      # The family look (hero, palette, stylesheet) is defined once in the
      # Brain and imported by the renderer — never copied in here.
      - uses: actions/checkout@v4
        with:
          repository: PyAutoLabs/PyAutoBrain
          path: PyAutoBrain

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Render every surface (local parse, no network)
        run: |
          mkdir -p _site
          python scripts/board.py --html     > _site/index.html
          python scripts/board.py --badge    > _site/badge.json
          python scripts/board.py --state    > _site/state.json
          python scripts/board.py --md       > board.md
          cp board.md _site/dashboard.md
          python scripts/board.py --md-brief > readme_strip.md

      # The contract is owned by the Brain (board/_state.py +
      # board/state_schema.json); the Memory only emits it. A feed that has
      # drifted from the contract fails the job here, before Pages publishes
      # something the cockpit would reject.
      - name: Validate the cockpit feed against the Brain contract
        run: python3 PyAutoBrain/board/_state.py _site/state.json

      - name: Write the board to the job step summary
        run: cat board.md >> "$GITHUB_STEP_SUMMARY"

      - name: Update the README strip (own repo only, main only)
        if: github.ref == 'refs/heads/main'
        run: |
          python - <<'PY'
          import pathlib, re
          readme = pathlib.Path("README.md")
          text = readme.read_text()
          strip = pathlib.Path("readme_strip.md").read_text().strip()
          begin, end = "<!-- memory:begin -->", "<!-- memory:end -->"
          block = f"{begin}\n{strip}\n{end}"
          if begin in text and end in text:
              text = re.sub(re.escape(begin) + r".*?" + re.escape(end), block,
                            text, flags=re.DOTALL)
              readme.write_text(text)
          PY
          if ! git diff --quiet README.md; then
            git config user.name  "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add README.md
            git commit -m "docs(memory): auto-update knowledge-board strip [skip ci]"
            for attempt in 1 2 3; do
              if git push; then exit 0; fi
              git pull --rebase origin main || exit 1
            done
            echo "::error::could not push the README strip after 3 attempts"
            exit 1
          else
            echo "README strip unchanged — nothing to commit."
          fi

      # The Pages site is created once out-of-band (gh api -X POST
      # repos/<owner>/<repo>/pages -f build_type=workflow) — enablement here
      # cannot create it with the default token (the Hands lesson).
      - uses: actions/configure-pages@v5
        if: github.ref == 'refs/heads/main'

      - uses: actions/upload-pages-artifact@v3
        if: github.ref == 'refs/heads/main'
        with:
          path: _site

      - id: deployment
        uses: actions/deploy-pages@v4
        if: github.ref == 'refs/heads/main'