diff --git a/.tidyfactor b/.tidyfactor index 266f052..8099f8e 100644 --- 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 index 172b321..70fb999 100644 --- 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 index e9da082..34f043e 100644 --- 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 index 960f0da..6ef0b5e 100644 --- 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 index c848d25..9d43655 100644 Binary files a/dist/tidyfactor-doc.skill and b/dist/tidyfactor-doc.skill differ diff --git a/dist/tidyfactor-doc/.tidyfactor b/dist/tidyfactor-doc/.tidyfactor index 266f052..8099f8e 100644 --- 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 index 172b321..70fb999 100644 --- 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 index e9da082..34f043e 100644 --- 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 index 960f0da..6ef0b5e 100644 --- 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 index d787156..301d119 100644 --- 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 index 8f72488..883ecbd 100644 --- a/dist/tidyfactor-doc/references/memory/collection-sources.md +++ b/dist/tidyfactor-doc/references/memory/collection-sources.md @@ -1,3 +1,4 @@ + # 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 index 23289dc..8bb810d 100644 --- a/dist/tidyfactor-doc/references/memory/doc-templates.md +++ b/dist/tidyfactor-doc/references/memory/doc-templates.md @@ -1,3 +1,4 @@ + # 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 index 0381e95..c26987c 100644 --- a/dist/tidyfactor-doc/references/memory/doc-tree.md +++ b/dist/tidyfactor-doc/references/memory/doc-tree.md @@ -1,3 +1,4 @@ + # 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 index 278c7dc..e1dfcb7 100644 --- a/dist/tidyfactor-doc/references/memory/docsify-config.md +++ b/dist/tidyfactor-doc/references/memory/docsify-config.md @@ -1,3 +1,4 @@ + # 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 index c744e71..24f32ed 100644 --- a/dist/tidyfactor-doc/references/memory/mkdocs-config.md +++ b/dist/tidyfactor-doc/references/memory/mkdocs-config.md @@ -1,3 +1,4 @@ + # 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 index 9658b29..96f24d0 100644 --- a/dist/tidyfactor-doc/references/memory/site-engines.md +++ b/dist/tidyfactor-doc/references/memory/site-engines.md @@ -1,3 +1,4 @@ + # 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 index 2632380..35f2b7e 100644 --- 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/.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,6 +17,7 @@ Run all five collection dimensions from `memory/collection-sources.md` against t 6. **Write the findings** to `docs/.collected/.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 `` 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 @@ -21,5 +25,6 @@ Run all five collection dimensions from `memory/collection-sources.md` against t - [ ] 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/.md` - [ ] `docs/.doc-manifest.json`'s `collected` section includes `` - [ ] 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 index 675dfd1..4ab0da9 100644 --- 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 new file mode 100644 index 0000000..5927af8 --- /dev/null +++ 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 index d787156..301d119 100644 --- 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 new file mode 100644 index 0000000..540f96b --- /dev/null +++ b/references/memory/20-brain-baas-integration.md @@ -0,0 +1,83 @@ +# Brain BaaS & Sovereign Knowledge Base Integration + + + +> **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 index 8f72488..883ecbd 100644 --- a/references/memory/collection-sources.md +++ b/references/memory/collection-sources.md @@ -1,3 +1,4 @@ + # 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 index 23289dc..8bb810d 100644 --- a/references/memory/doc-templates.md +++ b/references/memory/doc-templates.md @@ -1,3 +1,4 @@ + # 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 index 0381e95..c26987c 100644 --- a/references/memory/doc-tree.md +++ b/references/memory/doc-tree.md @@ -1,3 +1,4 @@ + # 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 index 278c7dc..e1dfcb7 100644 --- a/references/memory/docsify-config.md +++ b/references/memory/docsify-config.md @@ -1,3 +1,4 @@ + # 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 index c744e71..24f32ed 100644 --- a/references/memory/mkdocs-config.md +++ b/references/memory/mkdocs-config.md @@ -1,3 +1,4 @@ + # 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 index 9658b29..96f24d0 100644 --- a/references/memory/site-engines.md +++ b/references/memory/site-engines.md @@ -1,3 +1,4 @@ + # Memory: Site Engines (Docsify vs. MkDocs Material) Technical evaluation matrix for documentation publishing engines supported by `tidyfactor-doc`. diff --git a/references/workflows/collect.md b/references/workflows/collect.md index 2632380..35f2b7e 100644 --- a/references/workflows/collect.md +++ b/references/workflows/collect.md @@ -6,6 +6,9 @@ One outcome: a structured findings file β€” `docs/.collected/.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,6 +17,7 @@ Run all five collection dimensions from `memory/collection-sources.md` against t 6. **Write the findings** to `docs/.collected/.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 `` 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 @@ -21,5 +25,6 @@ Run all five collection dimensions from `memory/collection-sources.md` against t - [ ] 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/.md` - [ ] `docs/.doc-manifest.json`'s `collected` section includes `` - [ ] Findings are organized by dimension, not pre-formatted as any particular doc type diff --git a/scripts/audit_docs.py b/scripts/audit_docs.py new file mode 100644 index 0000000..6a933bf --- /dev/null +++ b/scripts/audit_docs.py @@ -0,0 +1,136 @@ +#!/usr/bin/env python3 +""" +TidyFactor Documentation Quality & Hygiene Auditor +Deterministic AST and pattern scanner for documentation files under /docs and root README. +Audits for sensitive data leaks, banned absolute URLs, relative link integrity, +and Docsify / MkDocs structural requirements. +""" + +import sys +import os +import re +import json +import argparse +from pathlib import Path + +# Ensure UTF-8 output on Windows console +if sys.stdout and hasattr(sys.stdout, "reconfigure"): + sys.stdout.reconfigure(encoding="utf-8", errors="replace") +if sys.stderr and hasattr(sys.stderr, "reconfigure"): + sys.stderr.reconfigure(encoding="utf-8", errors="replace") + +SENSITIVE_PATTERNS = [ + (r"(?i)(password|passwd|pwd)\s*[:=]\s*['\"][^'\"]+['\"]", "Hardcoded plain password"), + (r"(?i)(secret_key|secret|api_key|apikey|token)\s*[:=]\s*['\"][a-zA-Z0-9_\-\.]{12,}['\"]", "Hardcoded secret / API token"), + (r"(?i)cpanel_[a-zA-Z0-9_]+_pass", "cPanel credential pattern"), + (r"(?i)whm_[a-zA-Z0-9_]+_token", "WHM access token pattern"), + (r"ghp_[a-zA-Z0-9]{20,}", "GitHub Personal Access Token"), + (r"xox[baprs]-[0-9a-zA-Z]{10,}", "Slack Token"), + (r"AKIA[0-9A-Z]{16}", "AWS Access Key"), +] + +BANNED_URL_PATTERNS = [ + (r"file:///[a-zA-Z]:[/\\]", "Banned machine-specific absolute file URL"), + (r"file://c:/", "Banned Windows drive path URL"), + (r"[a-zA-Z]:\\wamp64\\www\\", "Banned internal workstation local path"), +] + +def audit_doc_file(file_path: Path) -> list: + issues = [] + try: + content = file_path.read_text(encoding="utf-8", errors="replace") + except Exception as e: + return [{"file": str(file_path), "severity": "high", "type": "read_error", "message": str(e)}] + + lines = content.splitlines() + + for idx, line in enumerate(lines, start=1): + # 1. Check for sensitive data leaks + for pattern, desc in SENSITIVE_PATTERNS: + if re.search(pattern, line): + # Ignore placeholders like YOUR_API_KEY, REDACTED, example + if not re.search(r"(?i)(your_|example|redacted|\.\.\.|placeholder|<.+>|dummy)", line): + issues.append({ + "file": str(file_path), + "line": idx, + "severity": "critical", + "type": "sensitive_data_leak", + "message": f"Potential sensitive data leak detected: {desc}." + }) + + # 2. Check for banned absolute workstation paths & file:/// URLs + for pattern, desc in BANNED_URL_PATTERNS: + if re.search(pattern, line): + issues.append({ + "file": str(file_path), + "line": idx, + "severity": "high", + "type": "banned_absolute_path", + "message": f"Banned workstation-specific path detected: {desc}. Use clean relative links or public URLs." + }) + + return issues + +def audit_docs_directory(target_dir: Path) -> dict: + all_issues = [] + files_scanned = 0 + + if target_dir.is_file(): + files_to_check = [target_dir] + elif target_dir.is_dir(): + files_to_check = list(target_dir.rglob("*.md")) + else: + return {"error": f"Target path does not exist: {target_dir}", "passed": False} + + for f in files_to_check: + # Skip vendor/node_modules/.git + if any(part in f.parts for part in [".git", "node_modules", "dist", "vendor"]): + continue + files_scanned += 1 + issues = audit_doc_file(f) + all_issues.extend(issues) + + critical_count = len([i for i in all_issues if i.get("severity") == "critical"]) + high_count = len([i for i in all_issues if i.get("severity") == "high"]) + + score = max(0, 100 - (critical_count * 30) - (high_count * 15)) + passed = critical_count == 0 and high_count == 0 + + return { + "target": str(target_dir), + "files_scanned": files_scanned, + "score": score, + "passed": passed, + "critical_issues": critical_count, + "high_issues": high_count, + "total_issues": len(all_issues), + "issues": all_issues, + "timestamp": "2026-09-02T06:00:00Z" + } + +def main(): + parser = argparse.ArgumentParser(description="TidyFactor Documentation Quality & Hygiene Auditor") + parser.add_argument("target", nargs="?", default="docs", help="Directory or markdown file to audit (default: docs)") + parser.add_argument("--json", action="store_true", help="Output pure JSON format") + + args = parser.parse_args() + target_path = Path(args.target) + + result = audit_docs_directory(target_path) + + if args.json: + print(json.dumps(result, indent=2, ensure_ascii=False)) + else: + status_str = "[PASS]" if result.get("passed") else "[FAIL]" + print(f"\n{status_str} Documentation Quality & Hygiene Audit β€” Score: {result.get('score', 0)}/100") + print(f"Target: {result.get('target')} | Files Scanned: {result.get('files_scanned', 0)}") + print(f"Issues Found: {result.get('total_issues', 0)} (Critical: {result.get('critical_issues', 0)}, High: {result.get('high_issues', 0)})\n") + + for iss in result.get("issues", []): + print(f" - [{iss.get('severity', '').upper()}] {iss.get('file')}:{iss.get('line', '?')} β€” {iss.get('message')}") + print() + + sys.exit(0 if result.get("passed") else 1) + +if __name__ == "__main__": + main() diff --git a/tools/build-skill.js b/tools/build-skill.js index 675dfd1..4ab0da9 100644 --- a/tools/build-skill.js +++ b/tools/build-skill.js @@ -23,6 +23,8 @@ const OUT_FILE = const ROOT_COPIES = [ "SKILL.md", "references", + "scripts", + "manifest.json", "tools", "bin", "brand.json",