Creating a strong foundation

.github/workflows/deploy.yml

@@ -6,10 +6,10 @@ on:
       - main
   workflow_dispatch:
 
+# Least privilege at the workflow level; the deploy job widens this for itself.
+# Granting pages/id-token here would hand them to the build job too, which only needs to read.
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 # Only allow one deployment at a time
 concurrency:
@@ -20,31 +20,42 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      # Actions are pinned to commit SHAs (org policy: zizmor unpinned-uses).
+      # Update a pin by resolving the tag, e.g.:
+      #   gh api repos/actions/checkout/git/ref/tags/v4 --jq '.object.sha'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+
+      - name: Script tests
+        run: uv run --frozen python -m unittest discover -s tests -p "test_*.py"
+
+      - name: Lint docs
+        run: uv run --frozen python scripts/lint_docs.py --baseline
 
       - name: Build docs
         run: |
-          uv run \
-            --with zensical \
-            --index-url https://pypi.zensical.org/simple/ \
-            --extra-index-url https://pypi.org/simple/ \
-            zensical build
+          uv run --frozen python scripts/build_docs.py
 
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
           path: site
 
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    # Scoped to this job only -- these are what actions/deploy-pages needs.
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/lint.yml

@@ -0,0 +1,41 @@
+name: Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Least privilege: these jobs only read the repo.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      # Actions are pinned to commit SHAs (org policy: zizmor unpinned-uses).
+      # Update a pin by resolving the tag, e.g.:
+      #   gh api repos/actions/checkout/git/ref/tags/v4 --jq '.object.sha'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      # The generators use Jinja for raw Markdown and PyYAML for structured frontmatter.
+      - name: Install linter dependencies
+        run: pip install pyyaml==6.0.3 jinja2==3.1.6
+
+      - name: Script tests
+        run: python -m unittest discover -s tests -p "test_*.py"
+
+      - name: Lint documentation
+        run: python scripts/lint_docs.py --baseline
+
+      # Advisory: shows the full Phase 0 backlog without affecting the job result.
+      - name: Backlog (informational)
+        if: always()
+        run: python scripts/lint_docs.py || true

.gitignore

@@ -15,3 +15,6 @@ venv/
 .idea/
 .vscode/
 *.swp
+
+# Cached upstream sources for scripts/port_docs.py
+.sources/

.lintbaseline.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "Known violations at baseline time. Shrink to zero; never grow. Regenerate with: uv run python scripts/lint_docs.py --write-baseline",
+  "checks": [
+    "links",
+    "images",
+    "internal",
+    "stubs",
+    "frontmatter",
+    "orphans",
+    "fences",
+    "model-swap",
+    "admonitions",
+    "size",
+    "modeldata",
+    "css",
+    "generated"
+  ],
+  "count": 6,
+  "known": [
+    "stubs|docs/community/discord.md|stub: 46 chars of content (minimum 400)",
+    "stubs|docs/community/gemma-skills.md|stub: 62 chars of content (minimum 400)",
+    "stubs|docs/community/gemmaverse.md|placeholder link: example.com",
+    "stubs|docs/cookbook.md|stub: 395 chars of content (minimum 400)",
+    "stubs|docs/tools/index.md|stub: 144 chars of content (minimum 400)",
+    "stubs|docs/tools/model-selector.md|stub: 58 chars of content (minimum 400)"
+  ]
+}