fix: add public repo hygiene checks and tighten agent rules

Block tracked local paths and secret-like files in CI, expand gitignore, and remove localhost URL from contributor docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

.github/AGENTS.md

@@ -6,7 +6,7 @@ CI, deployment, and repository automation under `.github/`.
 
 | Workflow | Trigger | Purpose |
 |----------|---------|---------|
-| [workflows/ci.yml](workflows/ci.yml) | Push/PR to `main` | Markdown lint, internal link check, MkDocs build |
+| [workflows/ci.yml](workflows/ci.yml) | Push/PR to `main` | Markdown lint, repo hygiene, internal links, MkDocs build |
 | [workflows/pages.yml](workflows/pages.yml) | Push to `main` | Build MkDocs site and deploy to GitHub Pages |
 | [workflows/link-check-scheduled.yml](workflows/link-check-scheduled.yml) | Weekly + manual | External link check via Lychee |
 

.github/workflows/ci.yml

@@ -35,6 +35,13 @@ jobs:
           python-version: "3.12"
       - run: python scripts/check-internal-links.py
 
+  repo-hygiene:
+    name: Public repo hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: python scripts/check-public-repo-hygiene.py
+
   mkdocs:
     name: MkDocs build
     runs-on: ubuntu-latest

.gitignore

@@ -4,3 +4,11 @@ research/
 # MkDocs build output and generated site files
 site/
 docs/CONTRIBUTING.md
+
+# Secrets and local environment files
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx

AGENTS.md

@@ -46,6 +46,7 @@ Run before opening a PR:
 
 ```bash
 npx markdownlint-cli2 "**/*.md"
+python scripts/check-public-repo-hygiene.py
 python scripts/check-internal-links.py
 python scripts/prepare-mkdocs.py
 mkdocs build --strict
@@ -59,10 +60,14 @@ Site config lives in [mkdocs.yml](mkdocs.yml). The [Deploy GitHub Pages](.github
 
 ## Do not
 
-- Commit secrets or credentials.
+- Commit secrets, credentials, API keys, tokens, or private keys.
+- Commit local-only paths: `research/`, `site/`, `docs/CONTRIBUTING.md`, `.env`, or other generated build output.
+- Commit draft research, internal notes, or machine-local paths unless the user explicitly asks to publish them.
+- Use `git add -A` or `git add .` without reviewing the staged file list first.
 - Add unrelated tooling (frameworks, package.json, etc.) without explicit request.
 - Break relative links or leave orphaned files out of the table of contents.
 - Run destructive git commands unless the user explicitly asks.
+- Push to the remote unless the user explicitly asks.
 
 ## Related files
 

CONTRIBUTING.md

@@ -32,6 +32,7 @@ Add new channel guides under `docs/channels/`. Add cross-cutting topics under `d
 5. **Verify locally**
    ```bash
    npx markdownlint-cli2 "**/*.md"
+   python scripts/check-public-repo-hygiene.py
    python scripts/check-internal-links.py
    python scripts/prepare-mkdocs.py
    mkdocs build --strict
@@ -53,7 +54,7 @@ python scripts/prepare-mkdocs.py
 mkdocs serve
 ```
 
-Open [http://127.0.0.1:8000/Awesome-Ads/](http://127.0.0.1:8000/Awesome-Ads/) in your browser.
+Open the local URL printed by `mkdocs serve` (typically port 8000).
 
 ## Standards
 

scripts/AGENTS.md

@@ -7,6 +7,7 @@ Maintenance utilities for repository quality checks.
 | File | Purpose |
 |------|---------|
 | `check-internal-links.py` | Validates that relative `markdown` links resolve to existing files |
+| `check-public-repo-hygiene.py` | Fails if local-only paths or secret-like content are tracked in git |
 | `prepare-mkdocs.py` | Generates `docs/CONTRIBUTING.md` with site-relative links for MkDocs builds |
 
 ## check-internal-links.py

scripts/check-public-repo-hygiene.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Fail if local-only or generated paths are tracked in git."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+FORBIDDEN_TRACKED_PATHS = (
+    "research/",
+    "site/",
+    "docs/CONTRIBUTING.md",
+)
+
+FORBIDDEN_TRACKED_SUFFIXES = (
+    ".env",
+    ".pem",
+    ".key",
+    ".p12",
+    ".pfx",
+)
+
+SENSITIVE_CONTENT_PATTERNS = (
+    re.compile(r"-----BEGIN (?:RSA |OPENSSH |EC )?PRIVATE KEY-----"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"\bghp_[A-Za-z0-9]{20,}\b"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bsk_(?:live|test)_[A-Za-z0-9]{10,}\b"),
+)
+
+
+def tracked_files() -> list[str]:
+    result = subprocess.run(
+        ["git", "ls-files", "-z"],
+        cwd=ROOT,
+        check=True,
+        capture_output=True,
+    )
+    return [entry for entry in result.stdout.decode("utf-8").split("\0") if entry]
+
+
+def main() -> int:
+    errors: list[str] = []
+
+    for path in tracked_files():
+        if path.startswith(FORBIDDEN_TRACKED_PATHS) or path in FORBIDDEN_TRACKED_PATHS:
+            errors.append(f"Tracked local-only path must not be committed: {path}")
+            continue
+
+        if path.endswith(FORBIDDEN_TRACKED_SUFFIXES):
+            errors.append(f"Tracked secret-like file must not be committed: {path}")
+            continue
+
+        file_path = ROOT / path
+        if not file_path.is_file():
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+
+        for pattern in SENSITIVE_CONTENT_PATTERNS:
+            if pattern.search(content):
+                errors.append(
+                    f"Possible secret pattern in tracked file: {path} ({pattern.pattern})"
+                )
+                break
+
+    if errors:
+        print("Public repo hygiene check failed:\n", file=sys.stderr)
+        for error in errors:
+            print(f"  - {error}", file=sys.stderr)
+        return 1
+
+    print("Public repo hygiene check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())