Skip to main content

Nox / Knox Admin

Audience: Ops · Super-admins · Support · Engineering · Where in app: /admin/knox/* · Access: Super-admin only (verify — these are admin-portal routes behind the admin layout; the ms-ai knowledge/model/feedback endpoints are the super-admin management surface).

Naming note: Nox is the product name shown to users; Knox is the internal/code name. The admin routes and ms-ai modules use knox, the UI labels say "Nox". They are the same assistant.

These screens are the back office for the Nox assistant: read every conversation, triage thumbs-down feedback, pick which AI model powers each Nox role, author the knowledge documents that feed Nox's RAG retrieval, register the portal pages Nox can navigate users to, watch/cancel per-visitor auto-engage directives, and sync Nox's tool registry to the shared ElevenLabs voice agent.

What it does​

  • Conversations browser — cross-tenant list of Nox threads with per-turn tool-call audit logs and voice-call playback.
  • Feedback review — paginated rated turns (defaults to not_helpful) for debugging answer quality.
  • AI Models — map each Nox role (chat / narration / embedding / transcript enrichment) to a catalog (provider, model_id); exactly one default per role.
  • Knowledge authoring — collections + markdown documents that get chunked and embedded into the RAG store (knox_knowledge_chunks).
  • Page Registry — the catalog of portal pages Nox knows about, used by the navigation agent.
  • Visitor Watches — cross-company view + cancel of per-visitor notify / auto-engage directives, now with fire diagnostics.
  • Voice Tools — idempotent sync of the Nox tool registry into the shared ElevenLabs agent.
  • App Learning (new 2026-11) — review "where is X" product notes learned from calls and resolved support tickets; only approved notes reach Nox.
  • Quality (new 2026-11) — the daily Nox quality check: graded calls and chats, a morning note, Run now, Export.
  • Feature flags — the Nox platform switches live on Admin → Settings → Feature Flags, not here (see below).
  • Nox Funnel audit — cross-company funnel audit-log browser + per-contact trace, plus backfill triggers (see Nox Funnel).
  • No Nox beta gates left — the nox_funnel_beta_enabled toggle was removed on 2026-10-09 (backend 1f9742dc8, frontend ac19403a); the tenant's own nox_funnel.enabled ("Track the funnel") is the only switch, and FunnelStageService.getConfig() returns null while it is off so every !cfg guard keeps the funnel dark. The Agent K beta, Nox Activity, and Nox settings-changes toggles went on 2026-09-25 (f1d39fb38). The company detail screen keeps only the funnel backfill button.
  • Agent K admin lives elsewhere — sell-side pricing at /admin/agent-k and the Agent K Maintenance page at /admin/agent-k/maintenance (attribution backfill with job polling, legacy kk_tokens index fix, LinkedIn draft repair, Funnel source repair — see Nox Funnel) — see Agent K.
  • Also not under /admin/knox: the push-notification tester panel (admin push settings) and the Certified Implementation Partner admin are their own admin pages; the tenant-side funnel danger-zone reset (POST /company/:id/nox-funnel/reset) is in tenant settings, not admin.

How it works​

Tabs (frontend/src/views/admin/knox/KnoxAdminTabs.vue): Knowledge, Page Registry, AI Models, Conversations, Feedback, Voice Tools, Visitor Watches, App Learning, Quality, plus a Cost Tracking link-out. The Vue views live in frontend/src/views/admin/knox/ and the visitor-watch view in frontend/src/views/admin/visitor-watches/. Most knox screens call ms-ai directly via config.getAiApiUrl() (repository frontend/src/repositories/admin/knox.js), under /knox-agent/* and /knox-voice/*. Visitor Watches instead talk to the Node backend admin routes (frontend/src/repositories/admin/visitor-watches.js → /admin/visitor-watches*).

ms-ai controllers:

  • knox-admin.controller.ts — crm-backfill, models CRUD/default, conversations list+thread, feedback list (under knox-agent/admin/…).
  • knox-management.controller.ts — knowledge chunks, sources, pages, ingest, reembed (under knox-agent/knowledge/…).
  • knox-document.controller.ts — collections + documents + page-options (under knox-agent/documents/…).
  • knox-voice.controller.ts — voice call metadata/audio (knox-voice/calls/:thread_id) and the tool sync.

Knowledge documents are the authored source of truth; on save the document service (ms-ai/.../services/knox-document.service.ts) deletes the doc's old chunks, splits the markdown into semantic chunks, generates contextual embeddings, and stores them as knox_knowledge_chunks — that chunk table is what Nox actually retrieves at answer time.

Screens & fields​

Conversations — /admin/knox/conversations​

Source: KnoxConversations.vue + KnoxConversationDetail.vue → getKnoxConversations (GET /knox-agent/admin/conversations). Redesigned 2026-11-12 (frontend 8eb3abcf, ms-ai ba274def1) into two panes: a 360px list on the left, the open call or chat on the right (the old KnoxConversationModal.vue was cut down). A kind filter (All / Calls / Chats) plus a date preset (Today, Yesterday, Last 7/30/90 days, Custom…) and Company ID; call rows show call length and the ElevenLabs summary. A call's recording plays on click ("Recording is no longer available (deleted by ElevenLabs retention)" when purged). Delete (c93a24e7 / ms-ai a437ccadf) permanently removes every turn of a thread — DELETE /knox-agent/admin/conversations/threads/:id, behind a ConfirmDialog. One row per thread_id; defaults to the last 7 days server-side, max window 90 days.

Each list row shows a call/chat icon, the company name, how long ago, Call · <duration> (with a recording marker) or "Chat · N messages", and a one-line preview; the list pages server-side.

The detail pane loads getKnoxConversationThread (…/conversations/threads/:thread_id), which renders the whole thread chronologically with each turn's tool_calls (input / output / duration) inline, plus per-turn feedback notes. Each tool call also shows "Model saw (markdown)" — the curated markdown the LLM actually read (model_markdown, rendered by ms-ai knox-tool-markdown.ts and persisted per turn), with an honest truncation marker when the stored output was capped at 24KB; the copy-to-markdown export includes it fenced. For voice threads it also calls getKnoxVoiceCall (GET /knox-voice/calls/:thread_id) for the ElevenLabs summary, termination reason, duration, and audio_available; if audio exists, fetchKnoxVoiceAudioBlob pulls the recording as a blob (auth header can't ride a bare <audio src>) for playback. Audio returns 404 if deleted from ElevenLabs retention, 403 if the admin doesn't own the call.

Feedback — /admin/knox/feedback​

Source: KnoxFeedback.vue → getKnoxFeedback (GET /knox-agent/admin/feedback). Paginated rated turns; the debug case (not_helpful) is the default, but helpful is also supported. Filters: From/To, Company ID, sentiment. Each row shows: question, answer, the feedback badge (Helpful / Not helpful), routed_agent, primary_intent, feedback_note, thread_id, company_id, created_at.

AI Models — /admin/knox/models​

Source: KnoxModels.vue → getKnoxModels / createKnoxModel / updateKnoxModel / setKnoxModelDefault / deleteKnoxModel (/knox-agent/admin/models). Maps Knox roles to a (provider, model_id) in the shared ai_models catalog. Exactly one model per role is the active default. This page only attaches a catalog model to a role — pricing/catalog itself lives elsewhere (Cost Tracking → Models).

Roles (create dropdown): Chat (answers, ingestion, context), Narration (recording analysis), Embedding, Transcript enrichment. The v2 engine also resolves knox_v2_research (researchers, action checker; falls back to chat — set via ms-ai PUT /knox-v2/admin/research-model) and knox_v2_hunter (morning hunt, claim checker; falls back to narration → chat) from this table; those rows are not in the create dropdown.

ColumnField
Modeldisplay_name / model id
Providerprovider
Selectedis_default (the active model for the role)
Actionsedit / set default / delete

Create flow: pick role → pick a catalog model from the dropdown (eligibleCatalogModels, filtered by role) → provider/model_id auto-fill → optional display name. Backing entity: knox_ai_models (provider, model_id, display_name, role, is_active, is_default); a unique constraint enforces one (provider, model_id, role) and a partial index enforces one default per role.

Knowledge — /admin/knox (collections + documents)​

Source: KnoxKnowledge.vue → getKnoxCollectionTree / getKnoxDocuments / createKnoxCollection etc. (/knox-agent/documents/…). Left rail is the collection tree; main pane lists documents in the selected collection (or "All Documents") with a title/content/tag search and Bulk Import (KnoxBulkImportModal.vue) + New Document.

Collections (knox_knowledge_collections): name, slug (unique), description, icon, parent_id (nestable), sort_order, document_count, is_active. A collection with documents can't be hard-deleted (FK RESTRICT); soft-delete via is_active=false. The tree now has a delete-collection button with a ConfirmDialog.

Document editor — /admin/knox/doc/new, /admin/knox/doc/:id​

Source: KnoxDocEditor.vue → getKnoxDocument / saveKnoxDocument / deleteKnoxDocument (/knox-agent/documents). Markdown authoring surface. Editing/saving a document re-chunks and re-embeds it into the RAG store.

Document entity (knox_knowledge_documents):

FieldNotes
title
markdown_contentfull markdown source
content_typefeature_guide (default) · how_to · troubleshooting · policy · api_reference · pricing · glossary
product_areaintegrations, billing, chat, …
plan_scopeall (default) · starter · growth · pro · enterprise
tags[]
related_urls[]portal page URLs this doc covers (picker fed by getKnoxPageOptions → /knox-agent/documents/page-options) — rendered as inline links in answers
collectionrequired FK — every doc belongs to one collection, no orphans
statusdraft · processing · published · failed
chunk_counthow many chunks were generated
processing_error, last_processed_at, author_id, version, is_activeprocessing/authoring metadata

The resulting chunks (knox_knowledge_chunks) carry content, context, feature_area, content_type, keywords[], requires_role, difficulty, two 1536-dim vector embeddings, and is_active. Admins can also browse/edit chunks directly via getKnoxChunks / updateKnoxChunk and trigger reembedAllKnoxChunks (POST /knox-agent/knowledge/reembed).

Page Registry — /admin/knox/pages, …/pages/create, …/pages/:id/edit​

Source: knox/pages/List.vue + knox/pages/Edit.vue → getKnoxPages / createKnoxPage / updateKnoxPage / deleteKnoxPage / seedKnoxPages (/knox-agent/knowledge/pages). The catalog of portal pages Nox's navigation agent can route users to.

List filters: search (URL/title/section/role), feature area, status (All / Active only / Inactive only). List columns: Page, URL Pattern, Feature Area, Role, Status, Actions.

Edit form (entity knox_page_registry):

FieldNotes
url_patternunique — e.g. /settings/integrations/shopify
title
feature_areapick or type
Breadcrumb / parent_urle.g. Settings > Integrations > Shopify / /settings/integrations
requires_rolepublic · user · admin (default) · agency
description
keywords / aliasessearch/intent matching for navigation
UI Elementsjsonb list of {id, label, type} where type ∈ input / button / toggle / select / link / section

Visitor Watches — /admin/knox/visitor-watches​

Source: visitor-watches/Index.vue → getVisitorWatches / cancelVisitorWatch / getVisitorWatchEvents (Node backend /admin/visitor-watches*). Cross-company view of per-visitor Nox watch / auto-engage directives, plus a fired-events history sub-tab.

Directives filters: Status (active / done / expired / All), Type (notify / auto_engage / All), Company ID. Directive columns: Company, Person, Type, Recurrence, Confidence, Set by, Status, Last fired, Created, Actions (Cancel → DELETE /admin/visitor-watches/:id).

A Diagnostics column (admin-only — not rendered on the tenant list) explains why an active directive keeps not-firing: last_attempt_at, attempt_count, and last_skip_reason (tooltip "Matched N× — last match skipped: …"). Fields live on KnoxVisitorDirectiveModel and are stamped by PersonWatchService on every recognition attempt. Tenants have their own list/cancel surface (Settings → Nox, GET/DELETE /knox/visitor-watches).

Events history (survives the directive): filter by Company ID, Type (notify / auto_engage), Outcome (fired / fire_failed).

Nox Funnel audit — /admin/nox-funnel/*​

Source: views/admin/nox-funnel/AuditLogs.vue + ContactTrace.vue (repository repositories/admin/noxFunnel.js) → Node backend GET /admin/nox-funnel/audit-logs and GET /admin/nox-funnel/contacts/trace (AdminNoxFunnelController). Browses the 120-day nox_funnel_audit_logs trail (signals, dedupes, gates, stage flips, intercept throttles) cross-company, and traces one contact's full funnel history. Manual triggers: POST /admin/nox-funnel/backfill (seed a tenant that just turned the funnel on; refuses unless nox_funnel.enabled), /brief-send-hour-backfill (funnel-enabled companies still on the 9am brief → 5am), /reason-text-backfill.

Voice Tools — /admin/knox/voice-tools​

Source: KnoxVoiceTools.vue. Sync to ElevenLabs reads every tool registered in KnoxToolRegistry on ms-ai and mirrors it into the ElevenLabs workspace: new tools are created, existing tools updated (latest schema + webhook URL), removed tools deleted, and the shared "Knox" agent is upserted to point at the resulting tool set. Idempotent — safe to re-run, intended after editing the tool registry or a fresh deploy. The result panel reports the agent action + id, attached tool count, and created/updated/deleted counts (or a failure message). This is a registry-sync view, not a per-tool editor.

App Learning — /admin/knox/app-learning​

Source: AppLearning.vue → ms-ai GET / PATCH {AI_URL}/knox-agent/admin/product-notes[/:id] (ms-ai/src/knox-voice/nox-product-notes.controller.ts). Sub-tabs To review / Approved / Rejected. Each note shows where Nox pointed vs "Where it really is", with a badge — Possible map error, Owner's correction, From a support ticket, Found elsewhere, Confirmed — and for ticket notes "What support answered". Edit the text, then Approve/Save or Reject. Sources: findings from Nox calls (learning/product-learning.ts) and resolved, team-handled support tickets (backend OpsTicketService.learnFromResolved → ms-ai POST /knox-v2/internal/product-notes/from-ticket, key ticket|KK-n; re-resolving rewrites the note but keeps its review status). Approved notes (≤60, 5-min cache) reach the planner, claim checker, every page guide and the voice brief. Table: nox_product_notes.

Quality — /admin/knox/quality​

Source: Quality.vue (route admin-knox-quality, title "Nox Quality") → ms-ai knox-agent/admin/quality (AdminOnlyGuard): GET runs, GET runs/:id, GET runs/:id/export, POST run (202). Shows the morning note, an Outcome grade and a Transcript audit, with tiles Requests fully met, Conversations with friction, "Said done when it wasn't", Never answered or went silent — each compared with the last earlier run that graded something. Run now starts a check; Export (d9a50fb1 / ms-ai 6daec5fa0) downloads nox-quality-<label>.json with transcripts, engine runs and tool calls. The check runs daily after 05:00 NZ only when the nox_quality_check_enabled flag is on (see v2 engine). The disabled-button tooltip still names the old env var (NOX_QUALITY_ENABLED) — the switch is the feature flag now.

Nox feature flags (Admin → Settings)​

/admin/settings (frontend/src/views/admin/Settings.vue, Feature Flags section, data-test="flag-<key>") stores three Nox-related switches in the backend settings collection (super-admin POST /settings / PUT /settings/:id); all off until set, read with a 60s cache:

KeyLabelReplaced
nox_quality_check_enabledNox daily quality checkNOX_QUALITY_ENABLED
nox_voice_server_reportsServer-written call reportsNOX_VOICE_SERVER_REPORTS
agency_client_ticketsAgency client tickets (in-app tickets and Nox hand-offs of managed clients go to the agency)OPS_AGENCY_CLIENT_TICKETS

Details: platform switches. NOX_JEV_SHADOW (ms-ai) is still an env flag.

  • Agency own character — Admin → Agencies → agency detail has an nox_avatar dropdown (chirpy, bee, nexus, chatsmart — Chirpy the chick, Buzzy the bee, Nexus, Chatsmart 360; backend/app/lib/noxIdentity.js AVATARS). Agencies request one from Agency settings → AI Assistant → Request your own character, which arrives as an ops ticket (type: 'avatar', category feature, label "Own character") — there is no dedicated queue.
  • Nox hand-off tickets arrive in the ops support queue with channel nox (label "Raised by Nox").
  • Voice Previews (/admin/voice-previews, Content & Media) manages preview clips for voice pickers — shared with the AI agents, not a Nox page.

Behaviors & edge cases​

  • Nox vs Knox is a naming split, not two systems.
  • Saving a knowledge document re-chunks and re-embeds it — old chunks for that doc are deleted first, so a save is a full reprocess (status moves through processing; failed + processing_error on error).
  • Exactly one default model per role — setKnoxModelDefault flips the active model; deleting the default for a role needs another model promoted.
  • Conversations default to 7 days, max 90 — widen From/To to look further back.
  • Voice audio is retention-bound — 404 once ElevenLabs has purged the recording; 403 if the admin doesn't own the call.
  • CRM-link backfill (backfillCrmLinks → POST /knox-agent/admin/crm-backfill) re-syncs knox_visitor_profiles.ghl_contact_id from the backend source of truth, fixing CRM-linked / pipeline-stage metrics that undercount because the mirror only learns links reactively from GHL stage webhooks.

Technical implementation​

  • Frontend: frontend/src/repositories/admin/knox.js, frontend/src/repositories/admin/visitor-watches.js; views under frontend/src/views/admin/knox/ (incl. AppLearning.vue, Quality.vue, KnoxConversationDetail.vue) and frontend/src/views/admin/visitor-watches/.
  • ms-ai controllers: knox-admin.controller.ts, knox-management.controller.ts, knox-document.controller.ts, knox-voice.controller.ts.
  • ms-ai entities: knox-knowledge-document.entity.ts, knox-knowledge-collection.entity.ts, knox-knowledge-chunk.entity.ts, knox-page-registry.entity.ts, knox-ai-model.entity.ts.
  • Doc → chunk pipeline: ms-ai/src/knox-agent/services/knox-document.service.ts; retrieval: knox-knowledge.service.ts.
  • Voice tool sync: ms-ai/src/knox-voice/knox-agent-sync.service.ts, knox-voice-tools.service.ts, knox-voice-registry.store.ts.
  • Backend visitor-watch routes: backend/app/routes/adminVisitorWatchRoutes.js; funnel admin routes: backend/app/routes/adminNoxFunnelRoutes.js.
  • Removed gate routes: PUT /company/:_id/nox-funnel-beta (2026-10-09), …/agent-k-beta, …/nox-activity, and …/nox-config no longer exist.