/wbDoc — Exhaustive Simulation ()

/wbDoc is the technical writer. It reads code and produces documentation — JSDoc blocks, README files, API specs — without ever altering execution logic. The hard constraint: signature preservation. The agent injects comments and generates external files; it never touches a function body, return value, or import statement.

Read this if you want to know which output format the agent picks by default and where the boundary sits between /wbDoc (generates docs) and /wbExplain (generates explanations).

---

1. Role & target

Aspect	Behavior
Role	The Technical Writer. Translates code logic into standardized documentation formats.
Target	Source files (.js, .ts, .vue), directories, or API route files.
Cell scope	None. /wbDoc doesn't interact with plans.
Side effects allowed	Injecting JSDoc blocks into source files. Creating/updating README.md, swagger.yaml, .mdx files.
Side effects forbidden	Altering execution logic, renaming variables, changing imports, modifying function signatures.

The distinction from /wbExplain: /wbDoc produces persistent artifacts (JSDoc in-file, README on disk). /wbExplain produces ephemeral prose (stdout, no disk writes). Use /wbDoc when you want the documentation to live with the code; use /wbExplain when you want a one-time understanding.

---

2. Argument resolution

Form	Example	What /wbDoc does
Specific file	Command: /wbDoc src/utils/auth.js	Parses AST. Injects JSDoc blocks above every exported function/class.
Directory path	Command: /wbDoc packages/wb-core	Reads all index.js exports. Generates or updates packages/wb-core/README.md.
Comma-separated	Command: /wbDoc src/WBC.js,src/tierEnforcement.js	Documents both files. Cross-links their types where they share interfaces.
Wildcard glob	Command: /wbDoc src/api/**/*.js	Sweeps all route files. Generates a unified swagger.json or openapi.yaml.

The format selection is automatic based on the target type:

• Single .js/.ts file → JSDoc injection
• Directory → README.md generation
• API route files → OpenAPI/Swagger spec
• Override any default with --format

---

3. Flag matrix

Flag	Shortcut	Purpose
--format="<type>"	-f	Forces output format: jsdoc, readme, swagger, mdx. Overrides auto-detection.
--dry-run	-d	Previews the documentation block without writing to disk.
--sync	-S	Checks if existing docs match the current AST and updates only what changed.

--sync vs default. Without --sync, /wbDoc overwrites existing JSDoc blocks with fresh AST-derived versions. With --sync, it diffs the existing docs against the current AST and only updates what actually changed (renamed parameters, new return types, added functions). --sync is the safe mode for codebases with hand-tuned JSDoc.

---

4. Pipelines (the agent-native scenarios)

📋/wbDoc Exhaustive Simulation

JSDoc injection on wb-core's WBC.js/wbDoc core2/packages/wb-core/src/WBC.core.js,src/WBC.events.js

> /wbDoc core2/packages/wb-core/src/WBC.core.js,src/WBC.events.js

[SYSTEM] Targeting 2 files for JSDoc injection.

[AST] WBC.core.js: 4 exported functions, 1 class.

[AST] WBC.events.js: 3 exported functions, 0 classes.

[INJECT] WBC.core.js:

/**

* Initializes the WBC runtime environment.

* @param {WBCConfig} config - Configuration object from wb-core settings.

* @returns {WBCInstance} The initialized WBC instance.

*/

export function initWBC(config) { ... }

[INJECT] WBC.events.js:

/**

* Registers a delegated event handler on the WBC container.

* @param {string} eventType - DOM event name (e.g., 'click', 'input').

* @param {string} selector - CSS selector for delegation target.

* @param {Function} handler - Callback receiving the matched element.

*/

export function delegateEvent(eventType, selector, handler) { ... }

[CROSS-LINK] WBC.core.js → WBC.events.js: shared WBCInstance type.

[OK] JSDoc injected into 2 files. 7 functions documented.

⚠️ Note: After the WBC.js decomposition (row 3 in the current plan), the three new modules need documentation:

💠 Pipeline JSDoc injection on wb-core's WBC.js

After the WBC.js decomposition (row 3 in the current plan), the three new modules need documentation:

💠 Pipeline Strict mode on utility files before PR merge

Enforcing a JSDoc policy across all utility files:

💠 Pipeline Sync mode on existing documented code

The code changed but the JSDoc is stale:

---

5. Edge cases & refusals

Trigger	What /wbDoc does
File already has up-to-date JSDoc	No-op with ℹ️ Documentation is current. No changes needed. (unless --sync detects drift).
Heavy metaprogramming (eval(), dynamic proxies)	❌ AST cannot resolve dynamic exports. Manual documentation required for <file>.
-f="xml" (unsupported format)	⚠️ XML not supported. Available formats: jsdoc, readme, swagger, mdx. Defaulting to jsdoc.
JSON/config file target	⚠️ Cannot inject comments into JSON format. Skipping <file>.json.
Directory with no index.js	Scans all .js files for exports. README generation still works — it just won't have a single entry point to reference.

The distinction worth naming: /wbDoc writes to the code (JSDoc) or next to the code (README, swagger). /wbExplain writes about the code (to stdout). /wbCheck verifies that what /wbDoc wrote is still accurate (link checking, type verification). Three commands, three roles, no overlap.