@tidyfactor/doc 1.3.0 → 1.9.0

package/references/memory/collection-sources.md

@@ -1,47 +1,48 @@
-# Memory: collection-sources
-
-The five dimensions `collect` runs against a target, and exactly what to pull from each. Operational — no rationale.
-
-## 1. Code parsing
-
-- Extract existing docblocks/comments verbatim (don't paraphrase yet — that's `generate`'s job).
-- List every public function, method, class, exported type, and (for components) prop/slot/event definition.
-- Note which of these already have adequate comments vs. none vs. stale (comment doesn't match current signature).
-
-## 2. Commit history
-
-- `git log --follow -- <path>` for the target's files: pull commit messages that explain *why*, not routine messages ("fix typo").
-- Any available PR/MR descriptions touching the target: design decisions, rejected alternatives, known limitations mentioned by the author.
-- Flag any TODO/FIXME/HACK comments found alongside — they're often undocumented known issues.
-
-## 3. Runtime & environment
-
-- Every environment variable the target reads (grep for `getenv`/`process.env`/`$_ENV`/config-loader calls), with whether it's required or optional and any default.
-- Software dependencies and version constraints from the manifest (`composer.json`, `package.json`) that the target actually uses — not the whole project's dependency list.
-- Any stated hardware/resource limits (memory limits, timeout values, rate limits) found in config or comments.
-- **Sanitization Rule**: Never collect real values of secrets (API keys, passwords, JWT secrets, private IP addresses, database credentials). Store only the variable name, description, and a synthetic example placeholder (e.g. `sk_test_EXAMPLE123456`, `203.0.113.10`).
-
-## 4. User persona tracing
-
-- Classify the target's readership: **API consumer** (calls it from outside), **internal maintainer** (edits this code), **end-user** (uses a UI built on it), or a mix.
-- For each persona present, note which facts from the other four dimensions matter to them — this list is what `generate` uses to prioritize content per doc type.
-
-## 5. Error patterns
-
-- Every thrown exception / returned error code / rejected promise in the target, with the condition that triggers it.
-- How each error is meant to be handled or surfaced (caught and logged? bubbled to caller? shown to end-user?) — from code and any logging statements found.
-- Common failure modes mentioned in commit history or TODO comments that aren't yet reflected in actual error handling.
-- **Scrubbing Rule**: Redact real database connection strings, local absolute file paths (e.g. `/home/user/project/...`), or authorization headers that might appear in error logs or exception messages.
-
----
-
-## 🔒 Security & Link Sanitization Reference
-
-| Item Category | Dangerous / Prohibited | Mandatory Safe Replacement |
-|---|---|---|
-| API Keys / Tokens | `sk_live_948f98a7c...` | `YOUR_API_KEY_HERE` or `EXAMPLE_TOKEN_123` |
-| Passwords / DB Secrets | `P@ssw0rd2026!` | `your_secure_password` |
-| Server IPs | `192.168.1.15`, `45.33.21.99` | `203.0.113.1` (RFC 5737 doc range) |
-| Local Drive Paths | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` |
-| Local Workstation URLs | `http://localhost:8080/secret` | `https://api.example.com` or `http://localhost:PORT` |
-| User Home Dirs | `/home/developer/workspace/...` | `~/project` or `/path/to/project` |
+<!-- 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.
+
+## 1. Code parsing
+
+- Extract existing docblocks/comments verbatim (don't paraphrase yet — that's `generate`'s job).
+- List every public function, method, class, exported type, and (for components) prop/slot/event definition.
+- Note which of these already have adequate comments vs. none vs. stale (comment doesn't match current signature).
+
+## 2. Commit history
+
+- `git log --follow -- <path>` for the target's files: pull commit messages that explain *why*, not routine messages ("fix typo").
+- Any available PR/MR descriptions touching the target: design decisions, rejected alternatives, known limitations mentioned by the author.
+- Flag any TODO/FIXME/HACK comments found alongside — they're often undocumented known issues.
+
+## 3. Runtime & environment
+
+- Every environment variable the target reads (grep for `getenv`/`process.env`/`$_ENV`/config-loader calls), with whether it's required or optional and any default.
+- Software dependencies and version constraints from the manifest (`composer.json`, `package.json`) that the target actually uses — not the whole project's dependency list.
+- Any stated hardware/resource limits (memory limits, timeout values, rate limits) found in config or comments.
+- **Sanitization Rule**: Never collect real values of secrets (API keys, passwords, JWT secrets, private IP addresses, database credentials). Store only the variable name, description, and a synthetic example placeholder (e.g. `sk_test_EXAMPLE123456`, `203.0.113.10`).
+
+## 4. User persona tracing
+
+- Classify the target's readership: **API consumer** (calls it from outside), **internal maintainer** (edits this code), **end-user** (uses a UI built on it), or a mix.
+- For each persona present, note which facts from the other four dimensions matter to them — this list is what `generate` uses to prioritize content per doc type.
+
+## 5. Error patterns
+
+- Every thrown exception / returned error code / rejected promise in the target, with the condition that triggers it.
+- How each error is meant to be handled or surfaced (caught and logged? bubbled to caller? shown to end-user?) — from code and any logging statements found.
+- Common failure modes mentioned in commit history or TODO comments that aren't yet reflected in actual error handling.
+- **Scrubbing Rule**: Redact real database connection strings, local absolute file paths (e.g. `/home/user/project/...`), or authorization headers that might appear in error logs or exception messages.
+
+---
+
+## 🔒 Security & Link Sanitization Reference
+
+| Item Category | Dangerous / Prohibited | Mandatory Safe Replacement |
+|---|---|---|
+| API Keys / Tokens | `sk_live_948f98a7c...` | `YOUR_API_KEY_HERE` or `EXAMPLE_TOKEN_123` |
+| Passwords / DB Secrets | `P@ssw0rd2026!` | `your_secure_password` |
+| Server IPs | `192.168.1.15`, `45.33.21.99` | `203.0.113.1` (RFC 5737 doc range) |
+| Local Drive Paths | `file:///C:/path/to/project/...` | `./docs/guides/` or `project-root/` |
+| Local Workstation URLs | `http://localhost:8080/secret` | `https://api.example.com` or `http://localhost:PORT` |
+| User Home Dirs | `/home/developer/workspace/...` | `~/project` or `/path/to/project` |

package/references/memory/decision-points.md

@@ -0,0 +1,72 @@
+# Memory: decision-points
+
+<!-- last-verified: 2026-09-08 -->
+
+Operational decision framework for documentation architecture and codebase interview governance. Enforces Contextual Decision Layer (CDL v2.0) and Dual-Mode Decision Architect (DM-DA) protocols.
+
+---
+
+## 🏛️ Decision Dimensions (D1–D5)
+
+| Code | Decision Dimension | Options (Reference SSOT) | Default Fallback | Ambiguity / Trigger Condition |
+|:---:|---|---|---|---|
+| **D1** | **Documentation Purpose & Scope** | • `full_codebase` (Complete API surface + architecture guides)<br>• `api_surface_only` (Public exports, routes, and client SDKs)<br>• `internal_architecture` (Developer onboarding, ADRs, module contracts)<br>• `end_user_docs` (User guides, tutorials, setup walkthroughs) | `full_codebase` | When request asks to "document this project" without specifying audience or depth. |
+| **D2** | **Publishing Platform Engine** | • `mkdocs_material` (Static HTML compilation, lunr offline search, bilingual i18n)<br>• `docsify_spa` (Zero-build client runtime SPA, instant markdown preview)<br>• `static_markdown` (Raw markdown files under `/docs` with root README) | `mkdocs_material` (if python available) / `docsify_spa` | When user has not configured `mkdocs.yml` or `docs/index.html`. |
+| **D3** | **Target Persona & Linguistic Register** | • `bilingual_developer` (Arabic/English parallel guides, technical terminology)<br>• `api_consumer` (Strict English technical docs, contract signatures)<br>• `internal_maintainer` (Architecture rationale, git commit history context)<br>• `end_user` (Simplified bilingual non-technical user documentation) | `bilingual_developer` | When project has not specified language or target reader in `brand.yaml`. |
+| **D4** | **Hygiene & Redaction Policy** | • `strict_zero_leak` (Mandatory automated regex masking of all IPs, DB passwords, API tokens)<br>• `public_sdk_redaction` (Scrub all internal routes, mock endpoints only)<br>• `internal_audit_permissive` (Permit local loopback `127.0.0.1` and dummy sample envs) | `strict_zero_leak` | Mandatory for all public or open-source documentation generation. |
+| **D5** | **Collection Depth & Extraction Dimensions** | • `full_5_dimensions` (Source AST + Git commit rationale + Env vars + Personas + Error patterns)<br>• `signatures_and_types` (Public function/class docblocks only)<br>• `architecture_and_rationale` (Module boundaries, ADRs, and commit history) | `full_5_dimensions` | Decides computational depth of subsequent `collect` workflow. |
+
+---
+
+## 🧭 Dual Operational Modes (DM-DA)
+
+```
+[CDL v2.0 Protocol]
+       │
+       ▼
+ Context Delta Resolution ──(Unknowns = ∅)──► Instant Baseline Confirmation
+       │
+       ├─► [MODE A] 🎯 Smart 3-Round Protocol (Deterministic alignment in 3 rounds)
+       │         Round 1: Purpose & Target Audience
+       │         Round 2: Engine & Architecture
+       │         Round 3: Boundaries, Hygiene & Safe Defaults
+       │         └── Escalation Gate: Confirm OR Escalate to Mode B
+       │
+       └─► [MODE B] 🔥 Relentless Debate & Interview (Debate Mode)
+                 Continuous multi-turn interrogation challenging assumptions
+                 Forces binary trade-offs (static vs SPA, brevity vs depth)
+                 Terminates strictly on: "END DEBATE" / "اعتماد"
+                 Emits: architectural_debate_synthesis.md
+```
+
+### [MODE A] 🎯 Smart 3-Round Protocol (الارتجال الذكي المقيد)
+- **Round 1: Purpose & Scope (D1 + D3)**: Pinpoint primary documentation consumer and technical scope.
+- **Round 2: Architecture & Engine (D2 + D5)**: Select publishing engine and depth of code extraction.
+- **Round 3: Hygiene & Safe Defaults (D4 + Remaining)**: Enforce security scrubbing rules and apply defaults.
+- **Strict Termination**: Finishes at Round 3, saves snapshot, and presents the Escalation Gate:
+  > *"هل تعتمد هذه البنية المبدئية للبدء فوراً، أم تفضل تفعيل [نمط المناظرة 🔥 Debate Mode] لتفكيك الافتراضات واختبار صلابة الهيكلية التوثيقية؟"*
+
+### [MODE B] 🔥 Relentless Debate & Interview (الاستجواب والمناظرة اللانهائية — Debate Mode)
+- **Activation**: Direct `/debate`, or Mode A Round 3 escalation.
+- **Behavior**:
+  - Relentless multi-turn counter-questioning challenging documentation choices:
+    - *"Why choose Docsify client-side SPA if SEO and offline indexability are critical for external developers?"*
+    - *"Why document internal private methods if the primary goal is public API adoption?"*
+    - *"How will the team prevent confidential server IPs and auth secrets from slipping into generated guides?"*
+    - *"If the documentation is bilingual Arabic/English, how will code snippets and RTL UI callouts remain visually coherent without layout breakages?"*
+  - Exposes anti-patterns: bloated doc sets nobody reads, duplicate API references, undocumented environment configurations.
+  - Forces binary, uncompromising trade-offs.
+- **Termination**: Ends **only** when user signals `"END DEBATE"` or `"اعتماد"`.
+- **Deliverables**:
+  - Generates formal synthesis: `docs/architectural_debate_synthesis.md`.
+  - Persists confirmed parameters to `.tidyfactor/doc-brief.snapshot.yaml` and `.tidyfactor/doc-brief.md`.
+
+---
+
+## ⚡ Boolean Skip Conditions (Deterministic Bypass)
+
+Skip interactive questioning and adopt safe defaults immediately if ANY condition is met:
+1. **Existing Snapshot**: `.tidyfactor/doc-brief.snapshot.yaml` exists and `track_staleness` confirms zero file drift.
+2. **Explicit User Declaration**: User specifies complete parameters in the prompt (e.g. *"Init MkDocs Material docs for public API with strict redaction"*).
+3. **Direct Stack Command**: User calls specific engine commands directly (`/mkdocs` or `/docsify`).
+4. **Maintenance Mode**: An audit (`audit_docs`) or validation run (`validate_skill.py`) preserves current configurations.

package/references/memory/doc-templates.md

@@ -1,73 +1,102 @@
-# Memory: doc-templates
-
-Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings.
-
-## API reference (`docs/api/<target>.md`)
-
-```markdown
-# <Target> API Reference
-
-<one-line purpose, from code parsing findings>
-
-## <FunctionOrMethodName>
-
-<signature, stack-formatted per the matching stacks/*.md file>
-
-**Parameters**
-| Name | Type | Required | Description |
-|---|---|---|---|
-
-**Returns**: <type> — <description>
-
-**Throws / Errors**: <from error-patterns findings>
-
-**Example**
-<minimal usage example>
-
----
-<!-- repeat per public function/method/endpoint/component -->
-
-## See also
-<cross-links to related target docs, if any>
-```
-
-## README (project root `README.md`)
-
-```markdown
-# <Project Name>
-
-<one-line description>
-
-## Requirements
-<software dependencies + version constraints, from runtime & environment findings>
-
-## Setup
-<install steps, from runtime & environment findings>
-
-## Environment variables
-| Variable | Required | Default | Description | Example |
-|---|---|---|---|---|
-| `API_KEY` | Yes | — | Secret authentication token | `EXAMPLE_TOKEN_1234567890ABCDEFGH` |
-| `DB_HOST` | Yes | `localhost` | Database host IP or hostname | `203.0.113.10` |
-| `DB_PASS` | Yes | — | Database user password | `your_secret_password` |
-
-## Usage
-<minimal example>
-
-## Documentation
-Full reference: [`/docs`](./docs/README.md)
-```
-
-## Guide (`docs/guides/<purpose-slug>.md`)
-
-```markdown
-# <Guide Title>
-
-<one-line: what this guide covers and who it's for, from persona-tracing findings>
-
-## <Section per logical step or concept>
-<content, prioritized for the target persona>
-
-## Related
-<links to other guides or API docs using relative paths, e.g. [API Overview](../api/project.md)>
-```
+<!-- last-verified: 2026-09-09 -->
+# Memory: doc-templates
+
+Shapes for each doc type `generate` produces. Templates, not prose — fill in from `collect` findings.
+
+## API reference (`docs/api/<target>.md`)
+
+```markdown
+# <Target> API Reference
+
+<one-line purpose, from code parsing findings>
+
+## <FunctionOrMethodName>
+
+<signature, stack-formatted per the matching stacks/*.md file>
+
+**Parameters**
+| Name | Type | Required | Description |
+|---|---|---|---|
+
+**Returns**: <type> — <description>
+
+**Throws / Errors**: <from error-patterns findings>
+
+**Example**
+<minimal usage example>
+
+---
+<!-- repeat per public function/method/endpoint/component -->
+
+## See also
+<cross-links to related target docs, if any>
+```
+
+## README (project root `README.md`)
+
+```markdown
+# <Project Name>
+
+<one-line description>
+
+## Requirements
+<software dependencies + version constraints, from runtime & environment findings>
+
+## Setup
+<install steps, from runtime & environment findings>
+
+## Environment variables
+| Variable | Required | Default | Description | Example |
+|---|---|---|---|---|
+| `API_KEY` | Yes | — | Secret authentication token | `EXAMPLE_TOKEN_1234567890ABCDEFGH` |
+| `DB_HOST` | Yes | `localhost` | Database host IP or hostname | `203.0.113.10` |
+| `DB_PASS` | Yes | — | Database user password | `your_secret_password` |
+
+## Usage
+<minimal example>
+
+## Documentation
+Full reference: [`/docs`](./docs/README.md)
+```
+
+## Guide (`docs/guides/<purpose-slug>.md`)
+
+```markdown
+# <Guide Title>
+
+<one-line: what this guide covers and who it's for, from persona-tracing findings>
+
+## <Section per logical step or concept>
+<content, prioritized for the target persona>
+
+## Related
+<links to other guides or API docs using relative paths, e.g. [API Overview](../api/project.md)>
+```
+
+## CHANGELOG (project root `CHANGELOG.md`)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### 🚀 Added
+- <new feature description>
+
+### 🐛 Fixed
+- <bug fix description>
+
+## [1.0.0] - 2026-09-09
+
+### 🚀 Added
+- Initial production release.
+- <feature list>
+
+---
+```
+

package/references/memory/doc-tree.md

@@ -1,37 +1,38 @@
-# 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.
-
-## Folder shape
-
-```
-docs/
-├── README.md              # doc-site landing page (generated by init)
-├── .doc-manifest.json      # tracking file (generated by init, updated by collect/generate)
-├── .collected/              # raw findings from `collect`, one file per target — not site content
-│   └── <target>.md
-├── api/                     # one file per documented target — only if the project has an API surface
-│   └── <target>.md
-└── guides/                  # one file per guide purpose — only once at least one guide exists
-    └── <purpose-slug>.md
-```
-
-No Empty Structures: `init` creates `api/` only if the stack detection found an API surface (endpoints, public package exports), and `guides/` is created lazily by the first `generate-guide` run, not by `init`. `.collected/` is created lazily by the first `collect` run.
-
-## `.doc-manifest.json` schema
-
-```json
-{
-  "project": "<name from composer.json/package.json>",
-  "stacks": ["php" | "js" | "ts" | "react" | "vue" | "next", "..."],
-  "collected": {
-    "<target>": "<ISO timestamp of last collect run>"
-  },
-  "generated": {
-    "<path relative to project root>": "<ISO timestamp of last generate run>"
-  }
-}
-```
-
-- `collected` and `generated` are separate: a target can be collected without anything generated from it yet.
-- `generated` entries aren't limited to `/docs` paths — `generate-readme` writes to root `README.md` and `generate-inline` touches source files, both still tracked here for audit purposes.
+<!-- 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.
+
+## Folder shape
+
+```
+docs/
+├── README.md              # doc-site landing page (generated by init)
+├── .doc-manifest.json      # tracking file (generated by init, updated by collect/generate)
+├── .collected/              # raw findings from `collect`, one file per target — not site content
+│   └── <target>.md
+├── api/                     # one file per documented target — only if the project has an API surface
+│   └── <target>.md
+└── guides/                  # one file per guide purpose — only once at least one guide exists
+    └── <purpose-slug>.md
+```
+
+No Empty Structures: `init` creates `api/` only if the stack detection found an API surface (endpoints, public package exports), and `guides/` is created lazily by the first `generate-guide` run, not by `init`. `.collected/` is created lazily by the first `collect` run.
+
+## `.doc-manifest.json` schema
+
+```json
+{
+  "project": "<name from composer.json/package.json>",
+  "stacks": ["php" | "js" | "ts" | "react" | "vue" | "next", "..."],
+  "collected": {
+    "<target>": "<ISO timestamp of last collect run>"
+  },
+  "generated": {
+    "<path relative to project root>": "<ISO timestamp of last generate run>"
+  }
+}
+```
+
+- `collected` and `generated` are separate: a target can be collected without anything generated from it yet.
+- `generated` entries aren't limited to `/docs` paths — `generate-readme` writes to root `README.md` and `generate-inline` touches source files, both still tracked here for audit purposes.