Knowledge base for tl-kb-builder.html — covers architecture, all steps/panels, every config field, wiring status, documented limitations, proxy checklist, and troubleshooting.
The KB Article Builder is a 5-step wizard for creating structured Knowledge Base articles inside the MSP AI Platform. Techs fill in article info, symptoms, procedure steps, notes, and tags — the builder assembles them into a formatted article ready for copy-paste into a KB system, export as plain text, or (when proxy is live) direct persistence to a backend KB API.
The tool is a sub-page served inside the MSP AI Platform parent shell. It loads ../nav.js to inherit the parent nav. All article generation logic is client-side JavaScript with no external runtime dependencies.
Article Types Supported
| Type | Icon | Use Case |
|---|---|---|
| Deployment Guide | 🚀 | Step-by-step install, onboarding, or setup of a tool or service |
| Break-Fix | 🔧 | Troubleshooting an error, failure, or incident with a known resolution |
| Policy / Config | 📋 | Standards, configuration references, compliance baselines, or policies |
| Action / Feature | Status | Notes |
|---|---|---|
| 5-step wizard UI | Live | Fully functional. Navigation, validation, preview all wired. |
| Article type selection | Live | Deploy / Break-Fix / Policy toggles update step 2 labels dynamically. |
| Symptom builder | Live | Dynamic add/remove, bound to symptoms[] array. |
| Step builder with CMD blocks | Live | Per-step toggle for CMD textarea. Rendered in preview and export. |
| Tag input | Live | Enter/comma to add, backspace to remove, suggestion pills. |
| Live preview (Step 5) | Live | buildPreview() renders full formatted article from current state. |
| Copy to clipboard | Live | navigator.clipboard.writeText — requires secure context (HTTPS or localhost). |
| Export plain text (.txt) | Live | Blob download. Filename: kb-{slug}-YYYY-MM-DD.txt |
| Product / OS / Affected pills in export | Fixed | FIX 4: previously these fields were silently dropped from buildPlainText() and submitArticle(). Now included. |
| KB ID generation | Client-side | KB-YYYYMMDD-XXXX — locally generated, not globally unique until persisted. |
| Article persistence (POST /kb/articles) | Activates when proxy is live | Commented-out fetch() in submitArticle(). Wire to custom KB backend. |
| IT Glue export | Activates when proxy is live | POST /itglue/documents — requires IT Glue API key in proxy. |
| ConnectWise ticket attach | Activates when proxy is live | POST /cw/service/tickets/{id}/notes — appends article to CW ticket. |
| nav.js parent injection | Via parent shell | FIX 6: script tag added. Loads ../nav.js deferred. Works when served from parent directory. |
| loadDashboard() / startAutoRefresh() / refreshAll() | Wired — demo mode | FIX 7: suite-standard proxy pattern added. No-op in demo. Activates when KB API endpoint is live. |
The KB Builder is a single-file, self-contained HTML application. All state is held in six JavaScript variables. There is no framework, no bundler, and no server-side rendering. The wizard flow is driven by goTo(step) which validates the current step before advancing.
State Variables
| Variable | Type | Holds |
|---|---|---|
| currentStep | int | Active wizard step (1–5) |
| selectedType | string | 'deploy' | 'fix' | 'policy' |
| selectedDiff | string | 'low' | 'med' | 'high' |
| selectedImpact | string | 'low' | 'med' | 'high' |
| selectedCallout | string | 'note' | 'tip' | 'warn' | 'danger' | 'none' |
| tags[] | string[] | All current tags |
| steps[] | object[] | { id, text, cmd, showCmd } per step |
| symptoms[] | string[] | All current symptom/overview entries |
Proxy-Ready Wiring Pattern
Article Output Pipeline
The same state is consumed by three output paths. All three were audited for completeness — the product/OS/affected/time fields were previously missing from the export and summary paths (fixed in FIX 4).
| Path | Function | Output |
|---|---|---|
| Live preview | buildPreview() | Formatted HTML rendered into #previewCard on Step 5 |
| Summary screen | submitArticle() | Populates #summaryWrap cards and sum-* elements |
| Plain text export | buildPlainText() | Structured .txt file with all fields, exported via Blob |
The original file contained <header class="topbar"> with a .tb-brand div containing the KTC logo and all associated CSS blocks (.topbar, .tb-brand, .tb-logo, .tb-name, .tb-right, .tb-btn, .tb-tag). These were removed. The page now uses the IVR-pattern topbar with the layer-badge and Orbitron h1, inheriting nav from the parent shell.
The original used JetBrains Mono / Exo 2 / Inter font stack, a #020406 background, and CSS tokens like --surface, --bdr, --txt2. All replaced with IVR ground-truth tokens: Orbitron / Share Tech Mono / Rajdhani, #0a0a0f bg, and the exact --panel / --border / --text / --cyan etc. variable set. Grid and scanline overlays match the IVR console exactly.
Original code always executed node${currentStep}.classList.add('done') regardless of direction. Navigating backward (e.g. step 3 → step 1) marked node3 as "done" even though the user was going back, leaving incorrect green "completed" markers on nodes the user went back past.
Fix: wrapped the done-add in a forward-only guard. When going backward, all nodes from the destination index onward have their "done" class removed.
Four pill groups captured state that was only used in buildPreview() but silently dropped from both buildPlainText() and submitArticle(): product/platform, OS scope, affected users, and time estimate. All four are now included in the plain-text export (added as labelled lines after Tags) and in a new "Product / OS / Affected" summary card plus "Est. Time" summary card. A helper function getPillVals(id) is used consistently across all three output paths.
The reset function used querySelectorAll('.toggle-opt, .prio-card, .pill') which missed .callout-opt buttons. After a reset, any previously selected callout type (Note / Tip / Warning / Critical) remained visually selected. Fixed by adding .callout-opt to the selector.
The file is a sub-page of the MSP AI Platform parent shell. The original file had no <script src="../nav.js" defer></script> tag. Added without touching any other functionality. Will silently 404 if opened standalone — expected behavior.
The original had no loadDashboard(), startAutoRefresh(30000), or refreshAll() — inconsistent with the rest of the console suite. All three added. isLive flag defaults false. Commented-out real fetch() call placed in submitArticle() for KB persistence. Demo banner added matching the IVR console pattern. Status dot shows DEMO MODE (yellow) / KB API ONLINE (green).
| Field | Required | Description |
|---|---|---|
| Article Title | ✓ | Free-text. Becomes article header. Validated non-empty on Next. |
| Author / Tech Name | ✓ | Free-text. Validated non-empty. Appears in preview meta and export. |
| Client / Account | Optional. Leave blank for general articles. Displayed in preview meta. | |
| Article Type | ✓ | Toggle: Deploy / Break-Fix / Policy. Drives step 2 label changes. Validated on Next. |
| Category | ✓ | Select: Backups, Networking, Security, Endpoints, Email, Identity, Cloud, Servers, Printing, Hardware, Other. |
| Difficulty | Card: Basic / Intermediate / Advanced. Stored in selectedDiff. Included in export. | |
| Affected Product / Platform | Multi-select pill group (13 options). Now included in export and summary (FIX 4). | |
| OS / Environment Scope | Multi-select pill group (9 options). Now included in export and summary (FIX 4). |
Labels and heading adapt based on article type selected in Step 1. "Deploy" shows "Use Case / Overview". "Break-Fix" shows "Symptoms / Triggers". "Policy" shows "Scope / Overview".
| Field | Required | Description |
|---|---|---|
| Symptoms / Use-Case list | ✓ | Dynamic add/remove rows. At least one non-empty entry required. Stored in symptoms[]. |
| Error Codes / Event IDs | Free text. Rendered as "Error Codes:" line in export if populated. | |
| Who is Affected | Multi-select pills (6 options). Now included in export and summary (FIX 4). | |
| Business Impact / Urgency | Card: Low / Medium / High. Stored in selectedImpact. Included in export. |
| Field | Required | Description |
|---|---|---|
| Steps (list) | ✓ | Dynamic add/remove. Each step has a text area and optional CMD toggle. At least one non-empty step required. Stored in steps[]. |
| CMD block (per step) | Optional per-step. Toggle button shows/hides a green-tinted mono textarea. Rendered in preview and export as "CMD: ..." line. | |
| Expected Outcome | Free text. Renders as bordered "Expected outcome:" line in preview and export. | |
| Estimated Time | Single-select pill (6 options). Now included in export and summary (FIX 4). |
| Field | Required | Description |
|---|---|---|
| Callout Type | Note / Tip / Warning / Critical / No callout. Stored in selectedCallout. Controls border/bg color in preview. Reset now correctly clears this (FIX 5). | |
| Callout Text | Free text. Only rendered if callout type is not "none" and text is non-empty. | |
| Related Articles | Free text. Rendered as "Related:" line in export if populated. | |
| Known Limitations / Gotchas | Free text. Rendered as "Gotchas:" line in export if populated. | |
| Tags | ✓ | Type + Enter or comma to add. Backspace removes last tag. At least one required. 12 suggestion pills available. |
buildPreview() fires when goTo(5) is called. Renders a live preview card showing exactly how the article will appear. All fields including product/OS/affected/time are rendered in the preview meta bar. Submitting calls submitArticle().
Shown after submitArticle() fires. The form and progress rail are hidden. Summary cards display all collected fields. Three action buttons are available.
| Button | Function | Status |
|---|---|---|
| Export Plain Text | exportArticle() | Live — Blob .txt download |
| Copy to Clipboard | copyArticle() | Live — navigator.clipboard (HTTPS required) |
| Build Another Article | resetBuilder() | Live — Full state reset, re-init |
| Action | Endpoint | Method | Status |
|---|---|---|---|
| Submit article (persist) | /kb/articles | POST | Activates when proxy is live |
| Export .txt | Blob download — no endpoint | N/A | Live |
| Copy to clipboard | navigator.clipboard API | N/A | Live — HTTPS required |
| IT Glue push | /itglue/documents | POST | Activates when proxy is live |
| CW Manage attach | /cw/service/tickets/{id}/notes | POST | Activates when proxy is live |
| KB article count | /kb/articles/count | GET | loadDashboard() seam — proxy live only |
| nav.js | ../nav.js (parent directory) | Script tag | Via parent shell |
| Google Fonts | fonts.googleapis.com | GET | External CDN |
Articles generate a local KB ID (KB-YYYYMMDD-XXXX) using Date + Math.random(). IDs are not globally unique across sessions and are not stored anywhere. Articles exist only in memory until exported or copied. Wire POST /kb/articles in submitArticle() when a KB backend is available.
There is no native KB article creation endpoint in the ConnectWise Manage REST API. CW Manage's closest option is POST /service/tickets/{id}/notes — attaching the article text as an internal note on a ticket. IT Glue has a Documents API (POST /documents) but requires an API key and auth headers managed by the proxy. Both require proxy activation.
ConnectWise Manage has no CSAT satisfaction score in the public REST API. Not applicable to this tool type but documented for suite consistency. Use SmileBack or Nicereply integrations for CSAT data.
navigator.clipboard.writeText() is restricted to secure contexts (HTTPS or localhost). On plain HTTP the call will be rejected. The export (.txt download) path works regardless of protocol.
Opening tl-kb-builder.html standalone will produce a 404 on ../nav.js. This is expected — the nav is injected by the parent shell. The wizard functionality works fully without the nav.
There is no localStorage draft save. Closing or refreshing the browser tab discards all wizard progress. A draft auto-save could be added by serialising state to localStorage on each step transition — not yet implemented.
- FIX 1: KTC home bar removed — sub-page pattern correct.
- FIX 2: IVR ground-truth theme applied — fonts, tokens, grid/scanline match.
- FIX 3: goTo() back-navigation bug fixed — no stale .done markers.
- FIX 4: Product / OS / Affected / Time included in export and summary.
- FIX 5: resetBuilder() .callout-opt clear added.
- FIX 6: nav.js script tag added.
- FIX 7: loadDashboard() / startAutoRefresh(30000) / refreshAll() wired. Demo banner active.
- Build POST /kb/articles endpoint in proxy — accepts full article payload, returns persisted ID.
- Set isLive = true in tl-kb-builder.html. Uncomment apiFetch() in submitArticle().
- Verify demo banner hides and status dot turns green on live load.
- If IT Glue push is needed: add API key to proxy, uncomment POST /itglue/documents call.
- If CW Manage attach is needed: pass ticket ID into submitArticle(), uncomment POST /cw/service/tickets/{id}/notes call.
- Draft auto-save: serialise steps[]/symptoms[]/tags[]/selectedType/etc. to localStorage on each goTo() call. Add "restore draft" prompt on load.
- KB search: add GET /kb/articles?q= endpoint and wire a search input to the summary action row.