TidyFactor · alwkala · Sep 2, 2026 · Sep 2, 2026
diff --git a/.tidyfactor b/.tidyfactor
@@ -1,6 +1,6 @@
 {
   "name": "tidyfactor-doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "category": "architecture",
   "description": "TidyFactor Doc - Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify)",
   "repository": "https://github.com/TidyFactor/Doc",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,11 +3,14 @@
 All notable changes to `tidyfactor-doc` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## [1.2.1] - 2026-08-25
+## [1.4.0] - 2026-09-02
 
-### Fixed
-- **CLI Executable & NPX Packaging**: Added standard `"add-skill": "bin/add-skill.js"` mapping in `package.json` to ensure unified `npx @tidyfactor/cli-doc add-skill` execution.
-- **Workflow Compliance**: Standardized `## Validation checklist` headers across all 8 workflows.
+### 🧠 Added — Sovereign Brain MCP Integration, Hygiene Auditor & Fail-Open Protocol
+- **Brain Integration Contract (`references/memory/20-brain-baas-integration.md`)**: Sovereign self-hosted architecture and Documentation Knowledge Item (KI) payload schemas.
+- **Fail-Open Active Discovery (`references/workflows/collect.md`)**: Local workspace auto-sensing first, optional Brain MCP context acceleration (`search_knowledge_base`) when active, and instant 0ms silent fallback.
+- **Runtime Tooling Manifest (`manifest.json`)**: Declared portable `audit_docs` tool conforming to `skill-manifest.tools.schema.json` with `"skill_root_anchor": "self"`.
+- **Documentation Quality & Hygiene Auditor (`scripts/audit_docs.py`)**: Sub-second AST and pattern scanner detecting sensitive credentials leaks, passwords, private tokens, and banned absolute workstation URLs.
+- **Tooling Scope & Anti-Triggers**: Enriched `SKILL.md` with explicit Rule 10 Tooling Scope and anti-triggers.
 
 ---
 

diff --git a/SKILL.md b/SKILL.md
@@ -31,6 +31,23 @@ Read only the command file that matches the request. Do not read all commands si
 6. **Zero Sensitive Data Leakage.** Under absolutely no circumstances should any real sensitive data (e.g., real API tokens, WHM/cPanel passwords, production server IPs, real DB credentials, secret keys, private auth tokens, or local absolute drive paths) be written into documentation. ALWAYS redact and replace these with safe generic placeholders.
 7. **Clean Relative Links Only.** Never include local machine filesystem URLs (such as `file:///C:/...`, `file:c:`, or absolute workstation paths) in documentation links or markdown cross-references. All document cross-links must use clean relative markdown paths or standard public web URLs (`https://...`).
 
+## Anti-Triggers
+
+- Do NOT use for writing marketing campaigns or sales copywriting (use `tidyfactor-marketing`).
+- Do NOT use for platform infrastructure management or deployment tasks (use `tidyfactor-github` or ops skills).
+
+## Tooling Scope (Rule 10)
+
+- **Execution Tools**:
+  - `audit_docs` (`scripts/audit_docs.py`): Sub-second AST & credential leak scanner for markdown docs under `/docs`.
+- **Contract & Schema**: Portably declared in `manifest.json` with `"skill_root_anchor": "self"`.
+- **Invocability**: Executable via direct CLI or through `tidyfactor-brain` MCP `run_skill_tool`.
+
+## Skill vs MCP Boundary (Rule 12)
+
+- **Inside Skill**: Static documentation templates, stack-specific docblock schemas, and local hygiene auditing scripts.
+- **MCP Layer**: Sovereign Brain persistence (`search_knowledge_base`, `extract_knowledge_item`) operating under the strict Fail-Open protocol (`references/memory/20-brain-baas-integration.md`).
+
 ## Sequencing
 
 `init` → `collect` → `generate` (repeatable, once per doc target) → `site` / `mkdocs` / `docsify` (optional, once /docs has real content).
diff --git a/brand.json b/brand.json
@@ -1,6 +1,6 @@
 {
   "name": "TidyFactor Doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "publisher": "TidyFactor Ecosystem",
   "partner": "Alwkala Digital Agency (https://alwkala.com)",
   "contact": {

diff --git a/dist/tidyfactor-doc.skill b/dist/tidyfactor-doc.skill
diff --git a/dist/tidyfactor-doc/.tidyfactor b/dist/tidyfactor-doc/.tidyfactor
@@ -1,6 +1,6 @@
 {
   "name": "tidyfactor-doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "category": "architecture",
   "description": "TidyFactor Doc - Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify)",
   "repository": "https://github.com/TidyFactor/Doc",

diff --git a/dist/tidyfactor-doc/CHANGELOG.md b/dist/tidyfactor-doc/CHANGELOG.md
@@ -3,11 +3,14 @@
 All notable changes to `tidyfactor-doc` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## [1.2.1] - 2026-08-25
+## [1.4.0] - 2026-09-02
 
-### Fixed
-- **CLI Executable & NPX Packaging**: Added standard `"add-skill": "bin/add-skill.js"` mapping in `package.json` to ensure unified `npx @tidyfactor/cli-doc add-skill` execution.
-- **Workflow Compliance**: Standardized `## Validation checklist` headers across all 8 workflows.
+### 🧠 Added — Sovereign Brain MCP Integration, Hygiene Auditor & Fail-Open Protocol
+- **Brain Integration Contract (`references/memory/20-brain-baas-integration.md`)**: Sovereign self-hosted architecture and Documentation Knowledge Item (KI) payload schemas.
+- **Fail-Open Active Discovery (`references/workflows/collect.md`)**: Local workspace auto-sensing first, optional Brain MCP context acceleration (`search_knowledge_base`) when active, and instant 0ms silent fallback.
+- **Runtime Tooling Manifest (`manifest.json`)**: Declared portable `audit_docs` tool conforming to `skill-manifest.tools.schema.json` with `"skill_root_anchor": "self"`.
+- **Documentation Quality & Hygiene Auditor (`scripts/audit_docs.py`)**: Sub-second AST and pattern scanner detecting sensitive credentials leaks, passwords, private tokens, and banned absolute workstation URLs.
+- **Tooling Scope & Anti-Triggers**: Enriched `SKILL.md` with explicit Rule 10 Tooling Scope and anti-triggers.
 
 ---
 

diff --git a/dist/tidyfactor-doc/SKILL.md b/dist/tidyfactor-doc/SKILL.md
@@ -31,6 +31,23 @@ Read only the command file that matches the request. Do not read all commands si
 6. **Zero Sensitive Data Leakage.** Under absolutely no circumstances should any real sensitive data (e.g., real API tokens, WHM/cPanel passwords, production server IPs, real DB credentials, secret keys, private auth tokens, or local absolute drive paths) be written into documentation. ALWAYS redact and replace these with safe generic placeholders.
 7. **Clean Relative Links Only.** Never include local machine filesystem URLs (such as `file:///C:/...`, `file:c:`, or absolute workstation paths) in documentation links or markdown cross-references. All document cross-links must use clean relative markdown paths or standard public web URLs (`https://...`).
 
+## Anti-Triggers
+
+- Do NOT use for writing marketing campaigns or sales copywriting (use `tidyfactor-marketing`).
+- Do NOT use for platform infrastructure management or deployment tasks (use `tidyfactor-github` or ops skills).
+
+## Tooling Scope (Rule 10)
+
+- **Execution Tools**:
+  - `audit_docs` (`scripts/audit_docs.py`): Sub-second AST & credential leak scanner for markdown docs under `/docs`.
+- **Contract & Schema**: Portably declared in `manifest.json` with `"skill_root_anchor": "self"`.
+- **Invocability**: Executable via direct CLI or through `tidyfactor-brain` MCP `run_skill_tool`.
+
+## Skill vs MCP Boundary (Rule 12)
+
+- **Inside Skill**: Static documentation templates, stack-specific docblock schemas, and local hygiene auditing scripts.
+- **MCP Layer**: Sovereign Brain persistence (`search_knowledge_base`, `extract_knowledge_item`) operating under the strict Fail-Open protocol (`references/memory/20-brain-baas-integration.md`).
+
 ## Sequencing
 
 `init` → `collect` → `generate` (repeatable, once per doc target) → `site` / `mkdocs` / `docsify` (optional, once /docs has real content).
diff --git a/dist/tidyfactor-doc/brand.json b/dist/tidyfactor-doc/brand.json
@@ -1,6 +1,6 @@
 {
   "name": "TidyFactor Doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "publisher": "TidyFactor Ecosystem",
   "partner": "Alwkala Digital Agency (https://alwkala.com)",
   "contact": {

diff --git a/dist/tidyfactor-doc/package.json b/dist/tidyfactor-doc/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "main": "SKILL.md",
   "bin": {

diff --git a/dist/tidyfactor-doc/references/memory/collection-sources.md b/dist/tidyfactor-doc/references/memory/collection-sources.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: collection-sources
 
 The five dimensions `collect` runs against a target, and exactly what to pull from each. Operational — no rationale.

diff --git a/dist/tidyfactor-doc/references/memory/doc-templates.md b/dist/tidyfactor-doc/references/memory/doc-templates.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: doc-templates
 
 Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings.

diff --git a/dist/tidyfactor-doc/references/memory/doc-tree.md b/dist/tidyfactor-doc/references/memory/doc-tree.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: doc-tree
 
 Canonical `/docs` folder shape and the manifest schema. Every command reads this before touching `/docs` so the structure stays identical across projects.

diff --git a/dist/tidyfactor-doc/references/memory/docsify-config.md b/dist/tidyfactor-doc/references/memory/docsify-config.md
@@ -1,3 +1,4 @@
+<!-- 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.

diff --git a/dist/tidyfactor-doc/references/memory/mkdocs-config.md b/dist/tidyfactor-doc/references/memory/mkdocs-config.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: MkDocs Material Configuration Spec
 
 Complete architectural specification for scaffolding and compiling production-grade documentation portals with MkDocs Material.

diff --git a/dist/tidyfactor-doc/references/memory/site-engines.md b/dist/tidyfactor-doc/references/memory/site-engines.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: Site Engines (Docsify vs. MkDocs Material)
 
 Technical evaluation matrix for documentation publishing engines supported by `tidyfactor-doc`.

diff --git a/dist/tidyfactor-doc/references/workflows/collect.md b/dist/tidyfactor-doc/references/workflows/collect.md
@@ -6,6 +6,9 @@ One outcome: a structured findings file — `docs/.collected/<target>.md` — th
 
 Run all five collection dimensions from `memory/collection-sources.md` against the target. Skip a dimension only if it genuinely doesn't apply (e.g., no Git history available for an uploaded snapshot) — note the skip and why, don't silently omit it.
 
+0. **Active Context Discovery & Brain MCP (Fail-Open)**:
+   - Silently check if project architecture KIs exist via `search_knowledge_base(query="architecture routes apis", scope="project")` when Brain MCP is active.
+   - If Brain MCP is absent or returns empty, proceed with 0ms delay directly to step 1.
 1. **Code parsing.** Extract existing docblocks/comments, function/method/class signatures, exported types, and public surface area directly from source. Flag anything already documented inline so `generate` doesn't duplicate it.
 2. **Commit history.** Read `git log` and any available PR descriptions for the target's files. Pull out *why* behind non-obvious code — rationale, past bugs fixed, deliberate tradeoffs — not just *what* changed.
 3. **Runtime & environment.** Enumerate required environment variables, config files, software dependencies (with version constraints), and any stated hardware/resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens found in `.env` or config files—record only variable names, expected formats, and generic placeholder values.
@@ -14,12 +17,14 @@ Run all five collection dimensions from `memory/collection-sources.md` against t
 
 6. **Write the findings** to `docs/.collected/<target>.md` as plain structured notes under five headings matching the dimensions above — this is source material for `generate`, not a finished doc, so skip prose polish.
 7. **Update `docs/.doc-manifest.json`**: add `<target>` to the `collected` section with a timestamp.
+8. **Optional Brain Sync (`--sync-brain`)**: Persist extracted architecture facts via `extract_knowledge_item` per `20-brain-baas-integration.md`.
 
 ## Validation checklist
 
 - [ ] `docs/.collected/<target>.md` exists and has content (or an explicit "not applicable" note) under all five dimension headings
 - [ ] Every fact traces to something actually found in the code, history, config, or logs — nothing inferred or assumed
 - [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets are replaced with safe generic placeholders
 - [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist in findings; all paths are normalized to project-relative paths
+- [ ] Deterministic audit passed via `python scripts/audit_docs.py docs/.collected/<target>.md`
 - [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`
 - [ ] Findings are organized by dimension, not pre-formatted as any particular doc type
diff --git a/dist/tidyfactor-doc/tools/build-skill.js b/dist/tidyfactor-doc/tools/build-skill.js
@@ -23,6 +23,8 @@ const OUT_FILE =
 const ROOT_COPIES = [
   "SKILL.md",
   "references",
+  "scripts",
+  "manifest.json",
   "tools",
   "bin",
   "brand.json",

diff --git a/manifest.json b/manifest.json
@@ -0,0 +1,29 @@
+{
+  "$schema": "https://tidyfactor.com/schemas/skill-manifest.tools.schema.json",
+  "skill_id": "tidyfactor-doc",
+  "version": "1.4.0",
+  "skill_root_anchor": "self",
+  "tools": [
+    {
+      "name": "audit_docs",
+      "description": "Audits documentation files under /docs for sensitive data leaks, banned absolute URLs, relative link integrity, and Docsify/MkDocs compliance.",
+      "runtime": "python",
+      "entrypoint": "scripts/audit_docs.py",
+      "args_schema": {
+        "type": "object",
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Directory or markdown file path to audit (defaults to docs)"
+          },
+          "json": {
+            "type": "boolean",
+            "description": "Output structured JSON report"
+          }
+        }
+      },
+      "cli_pattern": "python {entrypoint} {target} --json",
+      "isolation_recommended": false
+    }
+  ]
+}
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/doc",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "main": "SKILL.md",
   "bin": {

diff --git a/references/memory/20-brain-baas-integration.md b/references/memory/20-brain-baas-integration.md
@@ -0,0 +1,83 @@
+# Brain BaaS & Sovereign Knowledge Base Integration
+
+<!-- last-verified: 2026-09-02 -->
+
+> **Tier**: Core Intelligence Layer Contract  
+> **Authority**: Sovereign Self-Hosted & Local Multi-Tenant Architecture  
+> **Protocol**: Model B (Fail-Open Sovereign Agent Protocol)
+
+---
+
+## 🏛️ Architectural Doctrine & Deployment Model
+
+TidyFactor is strictly the **Intelligence, Context & Operating Layer** for AI agents. `tidyfactor-doc` operates under **Model B (Sovereign Self-Hosted Architecture)**:
+
+1. **Zero Centralized Data Exposure**: Codebase documentation, API schemas, and technical architectures are never transmitted to a centralized multi-tenant cloud service.
+2. **Local Multi-Tenant Isolation**: Each client or project maintains an isolated local SQLite knowledge base (`data/tenants/{tenant_id}_brain.sqlite`) or filesystem cache (`~/.gemini/knowledge/projects/{project_id}/`).
+3. **Fail-Open Invariant**: Brain MCP integration is completely optional at runtime. If `tidyfactor-brain` MCP is unavailable or disabled, `tidyfactor-doc` executes directly via local filesystem AST parsing and markdown generation with **0ms latency penalty** and zero connection errors.
+
+```
+┌────────────────────────────────────────────────────────┐
+│               AI Coding Agent Session                  │
+│       (Google Antigravity, Claude Code, Cursor)       │
+└───────────────────────────┬────────────────────────────┘
+                            │
+              [1] Check Active Tool Manifest
+                            │
+         ┌──────────────────┴──────────────────┐
+         │                                     │
+   [Brain MCP Active]                 [Brain MCP Absent]
+         │                                     │
+  [2] search_knowledge_base()                  │
+  (Doc Tree, APIs, Routes)                     │
+         │                                     │
+   (Found?)                                    │
+   ├── YES ──► Ingest KI Context               │
+   └── NO  ──► Direct Codebase Scan ◄──────────┘ (0ms Fail-Open)
+                            │
+               [3] Execute Doc Workflow
+               (init / collect / generate / site)
+                            │
+               [4] Persist /docs/ Artifacts
+                            │
+              (Optional: --sync-brain)
+                            │
+             [5] extract_knowledge_item()
+```
+
+---
+
+## 📋 Documentation Knowledge Item (KI) Payload Schema
+
+When persisting documentation structures or API contracts to the Brain via `--sync-brain`, payload objects MUST conform to the standard KI schema:
+
+```json
+{
+  "title": "Documentation Architecture: [Project Name]",
+  "category": "technical_architecture",
+  "scope": "project",
+  "tags": ["documentation", "api-reference", "mkdocs", "docsify", "architecture"],
+  "content": "### Codebase Overview\n...",
+  "metadata": {
+    "skill": "tidyfactor-doc",
+    "version": "1.4.0",
+    "site_engine": "mkdocs|docsify|none",
+    "doc_root": "docs/",
+    "entry_point": "docs/index.md",
+    "sidebar_configured": true,
+    "api_endpoints_count": 14,
+    "stacks": ["php", "typescript", "python"],
+    "i18n_enabled": true
+  }
+}
+```
+
+---
+
+## ⚡ Fail-Open Context Resolution Flow
+
+Every documentation command (`init`, `collect`, `generate`, `site`) executes context resolution deterministically:
+
+1. **Local Filesystem Scan**: Inspect `docs/`, `mkdocs.yml`, `_sidebar.md`, and project manifest (`package.json`, `composer.json`, `pyproject.toml`).
+2. **Optional Brain MCP Query**: If `search_knowledge_base` is active, retrieve existing architecture KIs for cross-referencing.
+3. **Silent Bypass**: If no Brain tool exists, complete the documentation task directly without prompting the user about server status.
diff --git a/references/memory/collection-sources.md b/references/memory/collection-sources.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: collection-sources
 
 The five dimensions `collect` runs against a target, and exactly what to pull from each. Operational — no rationale.

diff --git a/references/memory/doc-templates.md b/references/memory/doc-templates.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: doc-templates
 
 Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings.

diff --git a/references/memory/doc-tree.md b/references/memory/doc-tree.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: doc-tree
 
 Canonical `/docs` folder shape and the manifest schema. Every command reads this before touching `/docs` so the structure stays identical across projects.

diff --git a/references/memory/docsify-config.md b/references/memory/docsify-config.md
@@ -1,3 +1,4 @@
+<!-- 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.

diff --git a/references/memory/mkdocs-config.md b/references/memory/mkdocs-config.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: MkDocs Material Configuration Spec
 
 Complete architectural specification for scaffolding and compiling production-grade documentation portals with MkDocs Material.

diff --git a/references/memory/site-engines.md b/references/memory/site-engines.md
@@ -1,3 +1,4 @@
+<!-- last-verified: 2026-09-02 -->
 # Memory: Site Engines (Docsify vs. MkDocs Material)
 
 Technical evaluation matrix for documentation publishing engines supported by `tidyfactor-doc`.