From c79d009a1fee32b3415476d0499436dadde0ae66 Mon Sep 17 00:00:00 2001
From: Alex Macdonald-Smith <Alex.Mac@LoopTech.AI>
Date: Sun, 10 May 2026 18:09:42 -0400
Subject: [PATCH] =?UTF-8?q?feat(ci):=20tier-1=20community-repo=20polish=20?=
 =?UTF-8?q?=E2=80=94=20stale,=20semantic-pr,=20labeler,=20lychee,=20releas?=
 =?UTF-8?q?e-drafter,=20scorecard,=20first-interaction?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/labeler.yml                     | 55 +++++++++++++++
 .github/release.yml                     | 93 +++++++++++++++++++++++++
 .github/workflows/first-interaction.yml | 37 ++++++++++
 .github/workflows/labeler.yml           | 25 +++++++
 .github/workflows/lychee.yml            | 71 +++++++++++++++++++
 .github/workflows/release-drafter.yml   | 33 +++++++++
 .github/workflows/scorecard.yml         | 49 +++++++++++++
 .github/workflows/semantic-pr.yml       | 50 +++++++++++++
 .github/workflows/stale.yml             | 63 +++++++++++++++++
 .lychee.toml                            | 54 ++++++++++++++
 README.md                               |  1 +
 11 files changed, 531 insertions(+)
 create mode 100644 .github/labeler.yml
 create mode 100644 .github/release.yml
 create mode 100644 .github/workflows/first-interaction.yml
 create mode 100644 .github/workflows/labeler.yml
 create mode 100644 .github/workflows/lychee.yml
 create mode 100644 .github/workflows/release-drafter.yml
 create mode 100644 .github/workflows/scorecard.yml
 create mode 100644 .github/workflows/semantic-pr.yml
 create mode 100644 .github/workflows/stale.yml
 create mode 100644 .lychee.toml

diff --git a/.github/labeler.yml b/.github/labeler.yml
new file mode 100644
index 0000000..bc03c07
--- /dev/null
+++ b/.github/labeler.yml
@@ -0,0 +1,55 @@
+# Path-based PR labels for actions/labeler@v5.
+# Schema: <label>: [ { changed-files: [{ any-glob-to-any-file: [globs...] }] } ]
+
+"area:schemas":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "schemas/**"
+
+"area:scripts":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "scripts/**"
+
+"area:mcp":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "mcp/**"
+
+"area:cli":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "cli/**"
+
+"area:python-sdk":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "python-sdk/**"
+
+"area:site":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "site/**"
+
+"area:docs":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "docs/**"
+          - "README.md"
+          - "CONTRIBUTING.md"
+          - "CHANGELOG.md"
+
+"area:ci":
+  - changed-files:
+      - any-glob-to-any-file:
+          - ".github/workflows/**"
+          - ".github/labeler.yml"
+          - ".github/release.yml"
+
+"area:tests":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "tests/**"
+          - "**/__tests__/**"
+          - "**/*.test.*"
+          - "**/*.spec.*"
diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 0000000..1770efd
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,93 @@
+# Release-drafter configuration.
+# Used by .github/workflows/release-drafter.yml to auto-build draft release
+# notes whenever a PR merges into main.
+
+name-template: "v$RESOLVED_VERSION"
+tag-template: "v$RESOLVED_VERSION"
+
+categories:
+  - title: "🚀 Features"
+    labels:
+      - "feat"
+      - "feature"
+      - "type:feature"
+  - title: "🐛 Fixes"
+    labels:
+      - "fix"
+      - "bug"
+      - "type:bug"
+  - title: "📝 Docs"
+    labels:
+      - "docs"
+      - "area:docs"
+      - "documentation"
+  - title: "♻️ Refactor"
+    labels:
+      - "refactor"
+      - "type:refactor"
+  - title: "⚡ Performance"
+    labels:
+      - "perf"
+      - "performance"
+  - title: "🧪 Tests"
+    labels:
+      - "test"
+      - "tests"
+      - "area:tests"
+  - title: "🔒 Security"
+    labels:
+      - "security"
+  - title: "🤖 Dependencies"
+    labels:
+      - "dependencies"
+      - "dependabot"
+  - title: "🧹 Chore"
+    labels:
+      - "chore"
+      - "ci"
+      - "build"
+      - "area:ci"
+
+change-template: "- $TITLE (#$NUMBER) @$AUTHOR"
+change-title-escapes: '\<*_&'
+
+# Exclude unsigned/no-op work and label-only edits from the changelog body.
+exclude-labels:
+  - "skip-changelog"
+  - "duplicate"
+  - "invalid"
+  - "wontfix"
+
+version-resolver:
+  major:
+    labels:
+      - "breaking-change"
+      - "major"
+  minor:
+    labels:
+      - "feat"
+      - "feature"
+      - "minor"
+  patch:
+    labels:
+      - "fix"
+      - "bug"
+      - "docs"
+      - "chore"
+      - "ci"
+      - "build"
+      - "refactor"
+      - "perf"
+      - "test"
+      - "dependencies"
+      - "security"
+      - "patch"
+  default: patch
+
+# Build the draft body. Sections only render when they have entries.
+template: |
+  ## What's changed
+
+  $CHANGES
+
+  **Full changelog:** https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION
diff --git a/.github/workflows/first-interaction.yml b/.github/workflows/first-interaction.yml
new file mode 100644
index 0000000..ba7f73e
--- /dev/null
+++ b/.github/workflows/first-interaction.yml
@@ -0,0 +1,37 @@
+name: First interaction
+
+# Welcome first-time contributors with a friendly note pointing them at the
+# right docs. The action only runs the FIRST time someone interacts with the
+# repo, so we don't pester returning folks.
+
+on:
+  pull_request_target:
+    types: [opened]
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  greet:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # pin: v3.1.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          pr-message: >
+            Thanks for your first PR to understand-quickly! A maintainer will
+            review shortly. If this adds a new entry to `registry.json`, the
+            validate workflow will fetch your graph_url + check schema; if it
+            adds a new graph format, `CONTRIBUTING.md` walks through the schema
+            authoring flow. Questions:
+            [Discussions](https://github.com/looptech-ai/understand-quickly/discussions).
+          issue-message: >
+            Thanks for opening your first issue! For "add my repo" requests,
+            the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)
+            is often faster. For protocol questions, see
+            [CKGP v1](https://github.com/looptech-ai/understand-quickly/blob/main/docs/spec/code-graph-protocol.md)
+            or open a Discussions thread.
diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml
new file mode 100644
index 0000000..7580b6b
--- /dev/null
+++ b/.github/workflows/labeler.yml
@@ -0,0 +1,25 @@
+name: Labeler
+
+# Auto-apply `area:*` labels based on which files a PR touches. Keeps the PR
+# list grep-able and lets release-drafter sort changes into categories.
+#
+# Config: .github/labeler.yml - path globs map to label names.
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # pin: v5.0.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml
+          sync-labels: true
diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml
new file mode 100644
index 0000000..4c47252
--- /dev/null
+++ b/.github/workflows/lychee.yml
@@ -0,0 +1,71 @@
+name: Link check
+
+# Weekly sweep of every Markdown file + the live Pages site. Also runs on PRs
+# that touch README/docs so broken links never reach main.
+#
+# On scheduled-run failures we open (or reuse) a tracking issue rather than
+# failing silently. PR runs surface results as a job summary - no spammy issue.
+
+on:
+  schedule:
+    - cron: "17 6 * * 1"   # Mondays 06:17 UTC
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - "docs/**"
+      - ".lychee.toml"
+      - ".github/workflows/lychee.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  link-check:
+    name: lychee
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # pin: v5.0.0
+
+      - name: Restore lychee cache
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # pin: v4.3.0
+        with:
+          path: .lycheecache
+          key: lychee-${{ github.run_id }}
+          restore-keys: lychee-
+
+      - name: Run lychee
+        id: lychee
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # pin: v2.8.0
+        with:
+          args: >-
+            --config .lychee.toml
+            --cache
+            --no-progress
+            --verbose
+            './**/*.md'
+            'https://looptech-ai.github.io/understand-quickly/'
+          output: ./lychee/out.md
+          fail: false
+          format: markdown
+          jobSummary: true
+
+      - name: Open or update tracking issue on scheduled failures
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'schedule'
+        uses: peter-evans/create-issue-from-file@e8ef132d6df98ed982188e460ebb3b5d4ef3a9cd # pin: v5.0.1
+        with:
+          title: "Link check: broken links detected"
+          content-filepath: ./lychee/out.md
+          labels: |
+            area:docs
+            status:link-rot
+
+      - name: Fail job if links broken on PR
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'pull_request'
+        run: |
+          echo "::error::lychee reported broken links - see job summary."
+          exit 1
diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml
new file mode 100644
index 0000000..225e4d7
--- /dev/null
+++ b/.github/workflows/release-drafter.yml
@@ -0,0 +1,33 @@
+name: Release drafter
+
+# Maintains a permanent draft of the next GitHub Release. Every merged PR
+# bumps the resolved version and appends its title to the right category in
+# the release body, based on PR labels.
+#
+# Config lives in .github/release.yml.
+#
+# Cutting a release: edit the draft (rename/tag if needed), then Publish. The
+# tag created kicks off any tag-driven publish workflows.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  draft:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: release-drafter/release-drafter@67e173cadb2fbd3de94f4a861e0c48c913b462ae # pin: v6.4.0
+        with:
+          config-name: release.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 0000000..63ea718
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,49 @@
+name: OpenSSF Scorecard
+
+# Runs the OpenSSF Scorecard checks against this repo. Results are uploaded
+# as SARIF (visible under the Security tab) and published publicly so the
+# README badge can resolve them.
+#
+# Publish-results: requires the workflow to run from the default branch with
+# id-token write so the upstream can verify our identity. This is the
+# standard OSSF wiring.
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "12 4 * * 2"   # Tuesdays 04:12 UTC
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      security-events: write   # upload SARIF to Code Scanning
+      id-token: write          # publish_results: true
+      contents: read
+      actions: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # pin: v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@99c09fe975337306107572b4fdf4db224cf8e2f2 # pin: v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF results
+        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # pin: v3.27.0
+        with:
+          sarif_file: results.sarif
+          category: ossf-scorecard
diff --git a/.github/workflows/semantic-pr.yml b/.github/workflows/semantic-pr.yml
new file mode 100644
index 0000000..4082c81
--- /dev/null
+++ b/.github/workflows/semantic-pr.yml
@@ -0,0 +1,50 @@
+name: Semantic PR
+
+# Enforce Conventional Commits in PR titles. The squash-merge commit inherits
+# the PR title, so this keeps `git log main` parseable for release-drafter,
+# changelog tooling, and humans.
+#
+# Read-only check - we don't rewrite titles. The action posts a status; if it
+# fails, the PR author edits the title.
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  validate:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # pin: v5.5.3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            chore
+            ci
+            build
+            revert
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" found in the pull request title "{title}"
+            didn't match the configured pattern. Please ensure that the subject
+            starts with a lowercase letter.
+          wip: true
+          validateSingleCommit: false
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
new file mode 100644
index 0000000..68df936
--- /dev/null
+++ b/.github/workflows/stale.yml
@@ -0,0 +1,63 @@
+name: Stale
+
+# Auto-close inactive issues and PRs to keep the queue actionable.
+#
+# Policy:
+#   - Issues: 60 days idle -> mark stale + comment; close 15 days after that.
+#   - PRs:    30 days idle -> mark stale + comment; close 15 days after that.
+#   - Exempt anything pinned, security-tagged, an epic, or attached to a milestone.
+#   - Dependabot PRs are managed by Dependabot itself, so skip those entirely.
+#
+# Hand-edits an issue/PR? The stale label is removed automatically by actions/stale.
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # pin: v9.1.0
+        with:
+          days-before-issue-stale: 60
+          days-before-issue-close: 15
+          stale-issue-label: "status:stale"
+          stale-issue-message: >
+            This issue has been inactive for 60 days. Marking it `status:stale`
+            so it stays visible. If it's still relevant, drop a comment or remove
+            the label - otherwise it will close in 15 days. Thanks for taking
+            the time to file it.
+          close-issue-message: >
+            Closing this as stale. If you'd like to revisit, leave a comment and
+            we'll happily reopen.
+
+          days-before-pr-stale: 30
+          days-before-pr-close: 15
+          stale-pr-label: "status:stale"
+          stale-pr-message: >
+            This PR has been inactive for 30 days. Marking it `status:stale`.
+            A maintainer (or you) can push a new commit or drop a comment to
+            keep it open - otherwise it will auto-close in 15 days.
+          close-pr-message: >
+            Closing this as stale. Reopen any time once you're ready to pick it
+            back up - we don't delete the branch.
+
+          exempt-issue-labels: "pinned,security,epic"
+          exempt-pr-labels: "pinned,security,epic,dependencies"
+          exempt-all-milestones: true
+          exempt-draft-pr: true
+
+          # Don't antagonize Dependabot - it sweeps its own PRs.
+          exempt-pr-authors: "dependabot[bot],dependabot-preview[bot]"
+
+          operations-per-run: 100
+          ascending: true
+          remove-stale-when-updated: true
diff --git a/.lychee.toml b/.lychee.toml
new file mode 100644
index 0000000..852028b
--- /dev/null
+++ b/.lychee.toml
@@ -0,0 +1,54 @@
+# lychee link-checker config. Used by .github/workflows/lychee.yml.
+# Docs: https://lychee.cli.rs/
+
+# Network behavior
+max_redirects = 10
+max_concurrency = 8
+timeout = 20
+retry_wait_time = 2
+max_retries = 2
+
+# Treat these statuses as OK. Many sites block bot UAs with 403/429 even when
+# the URL itself is fine — we don't want flaky failures on link-check.
+accept = [200, 201, 202, 204, 206, 301, 302, 303, 304, 307, 308, 403, 429]
+
+# Don't try to dereference these — they're either local-only, intentional
+# placeholders in spec text, or rate-limited social platforms that hate bots.
+exclude = [
+  # Loopbacks and placeholders
+  "^https?://localhost",
+  "^https?://127\\.0\\.0\\.1",
+  "^https?://0\\.0\\.0\\.0",
+  "^https?://\\[::1\\]",
+  "^file://",
+
+  # Registry / spec example placeholders
+  "^https://raw\\.githubusercontent\\.com/yourname/",
+  "^https://github\\.com/yourname/",
+  "^https://example\\.com",
+  "^https://your-org\\.",
+
+  # Rate-limited / bot-hostile domains
+  "^https?://([a-z0-9-]+\\.)?linkedin\\.com",
+  "^https?://([a-z0-9-]+\\.)?twitter\\.com",
+  "^https?://([a-z0-9-]+\\.)?x\\.com",
+  "^https?://t\\.co",
+  "^https?://([a-z0-9-]+\\.)?facebook\\.com",
+  "^https?://([a-z0-9-]+\\.)?instagram\\.com",
+
+  # Anchors-only / mailto / tel
+  "^mailto:",
+  "^tel:",
+]
+
+# Use a polite, browser-ish UA. Some CDNs 403 the lychee default UA.
+user_agent = "Mozilla/5.0 (compatible; understand-quickly-linkcheck/1.0; +https://github.com/looptech-ai/understand-quickly)"
+
+# Cache between runs (workflow restores it)
+cache = true
+max_cache_age = "1d"
+
+# Where to scan when no explicit input is given (the workflow passes inputs
+# directly, but these are the defaults).
+include_verbatim = false
+no_progress = true
diff --git a/README.md b/README.md
index 4dcb3c1..2cacde6 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ Point AI agents at any indexed repo and they get a current, schema-validated gra
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 [![issues](https://img.shields.io/github/issues/looptech-ai/understand-quickly)](https://github.com/looptech-ai/understand-quickly/issues)
 [![last commit](https://img.shields.io/github/last-commit/looptech-ai/understand-quickly)](https://github.com/looptech-ai/understand-quickly/commits/main)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/looptech-ai/understand-quickly/badge)](https://scorecard.dev/viewer/?uri=github.com/looptech-ai/understand-quickly)
 
 <!-- Row 2 — distribution surfaces -->
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io)