chore: repository hygiene, metadata accuracy, and CI least-privilege pass

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,20 @@
+---
+name: Documentation issue
+about: Report a mistake, gap, or unclear section in the docs, README, or examples
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+
+---
+
+**Where**
+Link to the page or file (e.g. a https://freshcode-org.github.io/freshdata/ URL,
+`README.md`, or an `examples/` script) and the section heading.
+
+**What is wrong or missing**
+A clear description of the problem: incorrect statement, code snippet that
+doesn't run, broken link, missing explanation, outdated API, etc.
+
+**Suggested fix (optional)**
+If you already know what the text or snippet should say, propose it here —
+small doc fixes make great first PRs.

.github/workflows/ci.yml

@@ -12,6 +12,11 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
+# Least privilege by default; jobs that need more (nightly alert issue,
+# coverage-badge push) declare their own elevated permissions.
+permissions:
+  contents: read
+
 jobs:
   quality-fast:
     runs-on: ubuntu-latest

.github/workflows/fetch-fixtures.yml

@@ -5,6 +5,9 @@ on:
   schedule:
     - cron: "0 6 * * 1"  # weekly Monday 06:00 UTC
 
+permissions:
+  contents: read
+
 jobs:
   fetch:
     runs-on: ubuntu-latest

.github/workflows/nightly-real-model.yml

@@ -7,6 +7,9 @@ on:
     - cron: "0 4 * * *"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   real-model:
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'

.github/workflows/plugin-contract.yml

@@ -8,6 +8,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   plugin-contract:
     runs-on: ubuntu-latest

.github/workflows/reproducibility.yml

@@ -10,6 +10,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   reproducibility:
     runs-on: ubuntu-latest

.github/workflows/wheel-size.yml

@@ -10,6 +10,9 @@ on:
 env:
   MAX_WHEEL_BYTES: "2000000"
 
+permissions:
+  contents: read
+
 jobs:
   wheel-guard:
     runs-on: ubuntu-latest

.gitignore

@@ -15,6 +15,9 @@ htmlcov/
 .DS_Store
 .ipynb_checkpoints/
 
+# AI-assistant working artifacts (plans, task reports) — never committed
+.superpowers/
+
 # MkDocs build output
 site/
 

.pre-commit-config.yaml

@@ -1,4 +1,7 @@
-# Run `pre-commit install` after cloning. CI mirrors these checks.
+# Run `pre-commit install` after cloning. The ruff and mypy hooks match the
+# required CI lane; the hygiene hooks (whitespace, YAML/TOML syntax) are
+# pre-commit-only. There is deliberately no formatter hook: the codebase is
+# not `ruff format`-clean, and CI does not enforce formatting.
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
@@ -16,7 +19,6 @@ repos:
     hooks:
       - id: ruff
         args: [--fix]
-      - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.11.2