npm - @tidyfactor/doc - Versions diffs - 1.3.0 → 1.9.0 - Mend

@tidyfactor/doc 1.3.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

package/.tidyfactor +3 -3
package/CHANGELOG.md +103 -4
package/README.ar.md +34 -8
package/README.de.md +1 -1
package/README.es.md +1 -1
package/README.fa.md +1 -1
package/README.fr.md +1 -1
package/README.md +34 -8
package/README.pt.md +1 -1
package/README.zh.md +1 -1
package/SKILL.md +28 -5
package/bin/add-skill.js +44 -6
package/brand.json +1 -1
package/brand.yaml +10 -0
package/manifest.json +216 -0
package/package.json +4 -2
package/references/commands/adr.md +25 -0
package/references/commands/audit.md +15 -0
package/references/commands/brief.md +16 -0
package/references/commands/generate.md +7 -6
package/references/commands/site.md +25 -23
package/references/commands/vitepress.md +20 -0
package/references/memory/20-brain-baas-integration.md +83 -0
package/references/memory/adr-template.md +84 -0
package/references/memory/changelog-rules.md +58 -0
package/references/memory/collection-sources.md +48 -47
package/references/memory/decision-points.md +72 -0
package/references/memory/doc-templates.md +102 -73
package/references/memory/doc-tree.md +38 -37
package/references/memory/docsify-config.md +274 -273
package/references/memory/git-doc-sync-hook.md +54 -0
package/references/memory/mkdocs-config.md +171 -170
package/references/memory/naming-conventions.md +40 -0
package/references/memory/project-mindmap.md +66 -0
package/references/memory/site-engines.md +32 -34
package/references/memory/stacks/js-ts.md +47 -45
package/references/memory/stacks/php.md +35 -33
package/references/memory/stacks/react-vue-next.md +52 -50
package/references/memory/tone-of-voice.md +31 -0
package/references/memory/vitepress-config.md +174 -0
package/references/workflows/audit.md +42 -0
package/references/workflows/brief.md +105 -0
package/references/workflows/collect.md +60 -25
package/references/workflows/generate-adr.md +41 -0
package/references/workflows/generate-changelog.md +52 -0
package/references/workflows/init-docs.md +44 -18
package/references/workflows/vitepress.md +57 -0
package/scripts/audit_docs.py +190 -0
package/scripts/clean_orphaned_assets.py +185 -0
package/tools/build-skill.js +3 -0
package/assets/og-default.png +0 -0

package/references/memory/docsify-config.md CHANGED Viewed

@@ -1,273 +1,274 @@
-# Memory: docsify-config
-Fixed Docsify setup used by the `docsify` workflow. Not a menu of options — locked, production-tested config for TidyFactor documentation web portals.
-## `docs/index.html` Template
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title><PROJECT_NAME> Documentation</title>
-  <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
-  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;600;700&family=Inter:wght@400;500;600;700;800&family=Fira+Code:wght@400;500&display=swap">
-  <style>
-    :root {
-      --theme-color: #0A2540;
-      --sidebar-width: 300px;
-    }
-    body {
-      font-family: 'Inter', 'Cairo', -apple-system, BlinkMacSystemFont, sans-serif;
-      color: #1e293b;
-      background-color: #ffffff;
-    }
-    /* Header & Brand styling */
-    .app-name-link {
-      font-weight: 800 !important;
-      font-size: 1.25rem !important;
-      color: #0A2540 !important;
-      letter-spacing: -0.02em;
-    }
-    /* Fixed Floating Sidebar Toggle Hamburger Button */
-    .sidebar-toggle {
-      position: fixed !important;
-      top: 14px !important;
-      left: 14px !important;
-      bottom: auto !important;
-      z-index: 1000 !important;
-      background: #0A2540 !important;
-      padding: 10px 12px !important;
-      border-radius: 8px !important;
-      box-shadow: 0 4px 12px rgba(10, 37, 64, 0.25) !important;
-      border: none !important;
-      cursor: pointer !important;
-      width: auto !important;
-      height: auto !important;
-      transition: transform 0.2s ease, background 0.2s ease !important;
-    }
-    .sidebar-toggle:hover {
-      background: #081C30 !important;
-      transform: scale(1.04);
-    }
-    .sidebar-toggle .sidebar-toggle-button {
-      display: flex !important;
-      flex-direction: column !important;
-      justify-content: center !important;
-      align-items: center !important;
-      gap: 4px !important;
-      background: transparent !important;
-      padding: 0 !important;
-      margin: 0 !important;
-      border: none !important;
-      width: auto !important;
-      height: auto !important;
-    }
-    .sidebar-toggle span {
-      display: block !important;
-      background-color: #ffffff !important;
-      height: 2px !important;
-      width: 20px !important;
-      margin: 0 !important;
-      border-radius: 2px !important;
-      float: none !important;
-      position: relative !important;
-    }
-    /* Sidebar Layout */
-    .sidebar {
-      padding-top: 60px !important;
-      padding-bottom: 40px !important;
-      background-color: #f8fafc !important;
-      border-right: 1px solid #e2e8f0 !important;
-    }
-    .sidebar ul li a {
-      font-weight: 500;
-      color: #475569;
-      transition: all 0.15s ease;
-      border-radius: 4px;
-    }
-    .sidebar ul li a:hover {
-      color: #0A2540;
-      background-color: #e2e8f0/50;
-    }
-    .sidebar ul li.active > a {
-      color: #0A2540 !important;
-      font-weight: 700 !important;
-      border-left: 3px solid #0A2540;
-      padding-left: 8px;
-    }
-    /* Content Styling & Typography */
-    .markdown-section {
-      max-width: 900px !important;
-      padding: 40px 45px !important;
-    }
-    .markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4 {
-      font-family: 'Inter', 'Cairo', sans-serif;
-      color: #0F172A;
-      font-weight: 700;
-      letter-spacing: -0.02em;
-    }
-    .markdown-section h1 {
-      border-bottom: 1px solid #e2e8f0;
-      padding-bottom: 12px;
-      font-size: 2.1rem;
-    }
-    .markdown-section h2 {
-      font-size: 1.5rem;
-      margin-top: 2rem;
-    }
-    /* Code Blocks */
-    .markdown-section pre {
-      border-radius: 8px !important;
-      background-color: #0f172a !important;
-      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
-    }
-    .markdown-section code {
-      font-family: 'Fira Code', monospace !important;
-      font-size: 0.9em;
-    }
-    .markdown-section p code {
-      background-color: #f1f5f9 !important;
-      color: #0f172a !important;
-      padding: 3px 6px !important;
-      border-radius: 4px !important;
-      border: 1px solid #cbd5e1 !important;
-    }
-    /* Table Styling */
-    .markdown-section table {
-      display: table !important;
-      width: 100% !important;
-      border-collapse: collapse !important;
-      border: 1px solid #e2e8f0 !important;
-      border-radius: 6px !important;
-      overflow: hidden !important;
-      margin: 20px 0 !important;
-    }
-    .markdown-section th {
-      background-color: #f8fafc !important;
-      color: #0f172a !important;
-      font-weight: 700 !important;
-      border-bottom: 2px solid #e2e8f0 !important;
-      padding: 10px 14px !important;
-    }
-    .markdown-section td {
-      border-bottom: 1px solid #e2e8f0 !important;
-      padding: 10px 14px !important;
-    }
-    /* Scrollbars */
-    ::-webkit-scrollbar {
-      width: 8px;
-      height: 8px;
-    }
-    ::-webkit-scrollbar-track {
-      background: #f1f5f9;
-    }
-    ::-webkit-scrollbar-thumb {
-      background: #cbd5e1;
-      border-radius: 4px;
-    }
-    ::-webkit-scrollbar-thumb:hover {
-      background: #94a3b8;
-    }
-  </style>
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: '<PROJECT_NAME>',
-      repo: '<REPO_URL>',
-      loadSidebar: true,
-      alias: {
-        '/.*/_sidebar.md': '/_sidebar.md'
-      },
-      subMaxLevel: 2,
-      auto2top: true,
-      search: {
-        placeholder: 'Search documentation...',
-        noData: 'No results found',
-        depth: 3
-      }
-    }
-  </script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify@4"></script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
-  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
-</body>
-</html>
-```
-Replace `<PROJECT_NAME>` from `docs/.doc-manifest.json`'s `project` field, and `<REPO_URL>` with project repository or developer link (`https://github.com/alwkala/TidyFactor-Go`).
----
-## Critical Rules & Lessons Learned
-### 1. Subfolder Navigation Sidebar Alias
-- **CRITICAL**: Always configure `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` in `window.$docsify`. Without this alias, opening subfolder guides (e.g. `/#/guides/architecture-and-setup`) causes Docsify to look for `guides/_sidebar.md` and hide the sidebar menu!
-- **CRITICAL**: Use leading slashes `/` for all links in `_sidebar.md` (`/guides/admin-user-guide.md`, `/api/project.md`) so links resolve relative to the `/docs` root from any route depth.
-### 2. Localized Pages Inside Docs Root
-- **CRITICAL**: Docsify web root is `/docs`. Never link out of `/docs` using relative `../` paths (e.g. `../README.ar.md`), as Docsify SPA routing will throw `404 - Not Found`.
-- Always place localized landing pages inside `/docs` (e.g. `docs/README.ar.md`), rendering smoothly at `/#/README.ar.md`.
-### 3. Hamburger Toggle Button (`.sidebar-toggle`) Styling
-- Always style `.sidebar-toggle` and `.sidebar-toggle-button` with fixed positioning (`top: 14px; left: 14px; z-index: 1000`) and explicit `<span>` lines (`width: 20px; height: 2px; display: block`) so the hamburger button remains accessible without collapsing or overlapping sidebar text items.
-### 4. Cross-Platform Emojis & Typography
-- Country flag emojis (`🇸🇦`, `🇺🇸`) render as 2-letter codes (`SA`, `US`) on Windows Chrome/Edge. Use clean text badges (`[عربي]`, `[EN]`) in `_sidebar.md`.
-- Always load Google Fonts (`Cairo` for Arabic RTL, `Inter` for English LTR, `Fira Code` for code blocks) in `docs/index.html`.
----
-## `_sidebar.md` Generation Rule
-Group by audience/purpose, root docs first, using leading slashes `/`:
-```markdown
-- 🌐 [Overview / النظرة العامة](/README.md)
-- 📖 [المقدمة بالعربية](/README.ar.md)
-- 💡 [رؤية المنظومة والشركة](/guides/vision-and-ecosystem.md)
-- [عربي] أدلة المستخدم (User Guides - AR)
-  - [دليل مالك الموقع (Admin User Guide)](/guides/admin-user-guide.md)
-  - [دليل تحرير المحتوى (Editing Pages Content)](/guides/pages-editing-guide.md)
-- [EN] Developer & Technical Guides
-  - [Quick Start Guide](/guides/quick-start.md)
-  - [Platform & System Specifications](/guides/system-specifications.md)
-  - [AI Coding & Agent Workflows](/guides/ai-agent-workflows.md)
-  - [Content Engine Architecture & API](/guides/content-engine.md)
-  - [Architecture & Setup Guide](/guides/architecture-and-setup.md)
-  - [Database & Storage Architecture](/guides/database-and-storage.md)
-  - [Security & System Hardening](/guides/security-and-hardening.md)
-  - [Production Deployment & Hosting](/guides/deployment-and-hosting.md)
-  - [CMS Content Engine & Backups](/guides/cms-content-engine-and-backups.md)
-- 📚 REST API Reference
-  - [API Endpoints Specifications](/api/project.md)
----
-- 👨‍💻 Developed by [Alwkala](https://github.com/alwkala)
-```
-Regenerate the whole file each run so it never drifts from what's actually in `/docs`.
----
-## Preview
-Local static server: `php -S localhost:3001 -t docs` or `npx docsify-cli serve docs`.
+<!-- last-verified: 2026-09-02 -->
+# Memory: docsify-config
+Fixed Docsify setup used by the `docsify` workflow. Not a menu of options — locked, production-tested config for TidyFactor documentation web portals.
+## `docs/index.html` Template
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title><PROJECT_NAME> Documentation</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Cairo:wght@400;600;700&family=Inter:wght@400;500;600;700;800&family=Fira+Code:wght@400;500&display=swap">
+  <style>
+    :root {
+      --theme-color: #0A2540;
+      --sidebar-width: 300px;
+    }
+    body {
+      font-family: 'Inter', 'Cairo', -apple-system, BlinkMacSystemFont, sans-serif;
+      color: #1e293b;
+      background-color: #ffffff;
+    }
+    /* Header & Brand styling */
+    .app-name-link {
+      font-weight: 800 !important;
+      font-size: 1.25rem !important;
+      color: #0A2540 !important;
+      letter-spacing: -0.02em;
+    }
+    /* Fixed Floating Sidebar Toggle Hamburger Button */
+    .sidebar-toggle {
+      position: fixed !important;
+      top: 14px !important;
+      left: 14px !important;
+      bottom: auto !important;
+      z-index: 1000 !important;
+      background: #0A2540 !important;
+      padding: 10px 12px !important;
+      border-radius: 8px !important;
+      box-shadow: 0 4px 12px rgba(10, 37, 64, 0.25) !important;
+      border: none !important;
+      cursor: pointer !important;
+      width: auto !important;
+      height: auto !important;
+      transition: transform 0.2s ease, background 0.2s ease !important;
+    }
+    .sidebar-toggle:hover {
+      background: #081C30 !important;
+      transform: scale(1.04);
+    }
+    .sidebar-toggle .sidebar-toggle-button {
+      display: flex !important;
+      flex-direction: column !important;
+      justify-content: center !important;
+      align-items: center !important;
+      gap: 4px !important;
+      background: transparent !important;
+      padding: 0 !important;
+      margin: 0 !important;
+      border: none !important;
+      width: auto !important;
+      height: auto !important;
+    }
+    .sidebar-toggle span {
+      display: block !important;
+      background-color: #ffffff !important;
+      height: 2px !important;
+      width: 20px !important;
+      margin: 0 !important;
+      border-radius: 2px !important;
+      float: none !important;
+      position: relative !important;
+    }
+    /* Sidebar Layout */
+    .sidebar {
+      padding-top: 60px !important;
+      padding-bottom: 40px !important;
+      background-color: #f8fafc !important;
+      border-right: 1px solid #e2e8f0 !important;
+    }
+    .sidebar ul li a {
+      font-weight: 500;
+      color: #475569;
+      transition: all 0.15s ease;
+      border-radius: 4px;
+    }
+    .sidebar ul li a:hover {
+      color: #0A2540;
+      background-color: #e2e8f0/50;
+    }
+    .sidebar ul li.active > a {
+      color: #0A2540 !important;
+      font-weight: 700 !important;
+      border-left: 3px solid #0A2540;
+      padding-left: 8px;
+    }
+    /* Content Styling & Typography */
+    .markdown-section {
+      max-width: 900px !important;
+      padding: 40px 45px !important;
+    }
+    .markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4 {
+      font-family: 'Inter', 'Cairo', sans-serif;
+      color: #0F172A;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+    }
+    .markdown-section h1 {
+      border-bottom: 1px solid #e2e8f0;
+      padding-bottom: 12px;
+      font-size: 2.1rem;
+    }
+    .markdown-section h2 {
+      font-size: 1.5rem;
+      margin-top: 2rem;
+    }
+    /* Code Blocks */
+    .markdown-section pre {
+      border-radius: 8px !important;
+      background-color: #0f172a !important;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+    }
+    .markdown-section code {
+      font-family: 'Fira Code', monospace !important;
+      font-size: 0.9em;
+    }
+    .markdown-section p code {
+      background-color: #f1f5f9 !important;
+      color: #0f172a !important;
+      padding: 3px 6px !important;
+      border-radius: 4px !important;
+      border: 1px solid #cbd5e1 !important;
+    }
+    /* Table Styling */
+    .markdown-section table {
+      display: table !important;
+      width: 100% !important;
+      border-collapse: collapse !important;
+      border: 1px solid #e2e8f0 !important;
+      border-radius: 6px !important;
+      overflow: hidden !important;
+      margin: 20px 0 !important;
+    }
+    .markdown-section th {
+      background-color: #f8fafc !important;
+      color: #0f172a !important;
+      font-weight: 700 !important;
+      border-bottom: 2px solid #e2e8f0 !important;
+      padding: 10px 14px !important;
+    }
+    .markdown-section td {
+      border-bottom: 1px solid #e2e8f0 !important;
+      padding: 10px 14px !important;
+    }
+    /* Scrollbars */
+    ::-webkit-scrollbar {
+      width: 8px;
+      height: 8px;
+    }
+    ::-webkit-scrollbar-track {
+      background: #f1f5f9;
+    }
+    ::-webkit-scrollbar-thumb {
+      background: #cbd5e1;
+      border-radius: 4px;
+    }
+    ::-webkit-scrollbar-thumb:hover {
+      background: #94a3b8;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: '<PROJECT_NAME>',
+      repo: '<REPO_URL>',
+      loadSidebar: true,
+      alias: {
+        '/.*/_sidebar.md': '/_sidebar.md'
+      },
+      subMaxLevel: 2,
+      auto2top: true,
+      search: {
+        placeholder: 'Search documentation...',
+        noData: 'No results found',
+        depth: 3
+      }
+    }
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+</body>
+</html>
+```
+Replace `<PROJECT_NAME>` from `docs/.doc-manifest.json`'s `project` field, and `<REPO_URL>` with project repository or developer link (`https://github.com/alwkala/TidyFactor-Go`).
+---
+## Critical Rules & Lessons Learned
+### 1. Subfolder Navigation Sidebar Alias
+- **CRITICAL**: Always configure `alias: { '/.*/_sidebar.md': '/_sidebar.md' }` in `window.$docsify`. Without this alias, opening subfolder guides (e.g. `/#/guides/architecture-and-setup`) causes Docsify to look for `guides/_sidebar.md` and hide the sidebar menu!
+- **CRITICAL**: Use leading slashes `/` for all links in `_sidebar.md` (`/guides/admin-user-guide.md`, `/api/project.md`) so links resolve relative to the `/docs` root from any route depth.
+### 2. Localized Pages Inside Docs Root
+- **CRITICAL**: Docsify web root is `/docs`. Never link out of `/docs` using relative `../` paths (e.g. `../README.ar.md`), as Docsify SPA routing will throw `404 - Not Found`.
+- Always place localized landing pages inside `/docs` (e.g. `docs/README.ar.md`), rendering smoothly at `/#/README.ar.md`.
+### 3. Hamburger Toggle Button (`.sidebar-toggle`) Styling
+- Always style `.sidebar-toggle` and `.sidebar-toggle-button` with fixed positioning (`top: 14px; left: 14px; z-index: 1000`) and explicit `<span>` lines (`width: 20px; height: 2px; display: block`) so the hamburger button remains accessible without collapsing or overlapping sidebar text items.
+### 4. Cross-Platform Emojis & Typography
+- Country flag emojis (`🇸🇦`, `🇺🇸`) render as 2-letter codes (`SA`, `US`) on Windows Chrome/Edge. Use clean text badges (`[عربي]`, `[EN]`) in `_sidebar.md`.
+- Always load Google Fonts (`Cairo` for Arabic RTL, `Inter` for English LTR, `Fira Code` for code blocks) in `docs/index.html`.
+---
+## `_sidebar.md` Generation Rule
+Group by audience/purpose, root docs first, using leading slashes `/`:
+```markdown
+- 🌐 [Overview / النظرة العامة](/README.md)
+- 📖 [المقدمة بالعربية](/README.ar.md)
+- 💡 [رؤية المنظومة والشركة](/guides/vision-and-ecosystem.md)
+- [عربي] أدلة المستخدم (User Guides - AR)
+  - [دليل مالك الموقع (Admin User Guide)](/guides/admin-user-guide.md)
+  - [دليل تحرير المحتوى (Editing Pages Content)](/guides/pages-editing-guide.md)
+- [EN] Developer & Technical Guides
+  - [Quick Start Guide](/guides/quick-start.md)
+  - [Platform & System Specifications](/guides/system-specifications.md)
+  - [AI Coding & Agent Workflows](/guides/ai-agent-workflows.md)
+  - [Content Engine Architecture & API](/guides/content-engine.md)
+  - [Architecture & Setup Guide](/guides/architecture-and-setup.md)
+  - [Database & Storage Architecture](/guides/database-and-storage.md)
+  - [Security & System Hardening](/guides/security-and-hardening.md)
+  - [Production Deployment & Hosting](/guides/deployment-and-hosting.md)
+  - [CMS Content Engine & Backups](/guides/cms-content-engine-and-backups.md)
+- 📚 REST API Reference
+  - [API Endpoints Specifications](/api/project.md)
+---
+- 👨‍💻 Developed by [Alwkala](https://github.com/alwkala)
+```
+Regenerate the whole file each run so it never drifts from what's actually in `/docs`.
+---
+## Preview
+Local static server: `php -S localhost:3001 -t docs` or `npx docsify-cli serve docs`.

package/references/memory/git-doc-sync-hook.md ADDED Viewed

@@ -0,0 +1,54 @@
+<!-- last-verified: 2026-09-09 -->
+# Memory: git-doc-sync-hook
+Specification and configuration guide for pre-commit documentation synchronization hooks.
+## 1. Objective
+Prevent drift between code changes and documentation by verifying that when core functions, endpoints, or public APIs are modified in staged git commits, their corresponding documentation files in `/docs` or root `README.md` / `CHANGELOG.md` are also staged.
+## 2. Husky / Git Hook Implementation (`.husky/pre-commit` or `.git/hooks/pre-commit`)
+```bash
+#!/usr/bin/env bash
+# TidyFactor Doc Pre-Commit Guard
+set -e
+# 1. Check staged files
+STAGED_CODE=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(php|ts|js|py|go|rs)$' || true)
+STAGED_DOCS=$(git diff --cached --name-only --diff-filter=ACM | grep -E '(^docs/|README\.md|CHANGELOG\.md)' || true)
+# 2. If core code changed, verify documentation activity or bypass flag
+if [ -n "$STAGED_CODE" ]; then
+    # Check if core services / interfaces were modified
+    CORE_CHANGES=$(echo "$STAGED_CODE" | grep -E '(Core/|Services/|Controllers/|api/|interfaces/)' || true)
+    if [ -n "$CORE_CHANGES" ] && [ -z "$STAGED_DOCS" ]; then
+        if [ "$DOC_OVERRIDE" != "1" ]; then
+            echo ""
+            echo "❌ [TidyFactor Doc Guard] Core code modified without documentation update!"
+            echo "Staged core files:"
+            echo "$CORE_CHANGES"
+            echo ""
+            echo "Please update corresponding files under /docs or CHANGELOG.md."
+            echo "To bypass intentionally for hotfixes, run: DOC_OVERRIDE=1 git commit -m '...'"
+            echo ""
+            exit 1
+        fi
+    fi
+fi
+# 3. Run audit_docs on staged docs
+if [ -n "$STAGED_DOCS" ]; then
+    echo "🔍 [TidyFactor Doc Guard] Auditing staged documentation quality..."
+    python scripts/audit_docs.py docs/
+fi
+exit 0
+```
+## 3. Benefits
+- Enforces the Single Source of Truth rule.
+- Eliminates stale documentation where APIs evolve but docs remain outdated.
+- Runs sub-second link and secret checks before commit creation.