Customer Onboarding Guide

This is the master document for deploying Planara. It covers two paths:

• Dealer deployment — a single service operation using Planara for their technicians. Upload documentation, configure roles, go live. 2-4 weeks.
• OEM network deployment — an equipment manufacturer rolling Planara out to their dealer network. The OEM provisions and controls the content. Dealers consume it. Technician outcomes flow back as field intelligence. 4-8 weeks for the first wave, then self-serve expansion.

Both paths use the same infrastructure. The difference is who controls the content and who sees the analytics.

For quick evaluation, the self-serve onboarding pipeline generates a working configuration from a single PDF in under 30 minutes.

You are here

If this is your first tenant, this is the path. Five steps, in order. Each one has its own page — this is the map.

1. Provision tenant      →  /docs/operations/tenant-provisioning
   (namespace + admin user + branding)

2. Upload documents      →  /docs/content/ingestion
   (tag every document with equipment models — this matters,
   see /docs/concepts/equipment-scoping)

3. Review chunks         →  /docs/content/document-detail
   (quality score > 0.7, chunk count looks sane, spot-check
   spec tables and safety warnings)

4. Invite team           →  /docs/admin/team
   (technician + service writer + admin roles;
   technicians get the URL or QR code last, not first)

5. Run eval              →  /docs/quality/eval-management
   (auto-generated queries land in pending; review with a
   senior tech, promote to golden, set the baseline)

Steps 1-2 are usually same-day. Step 3 is where most first-time tenants stall — bad quality scores or wrong equipment tags here will haunt every query downstream. Steps 4-5 only happen after step 3 passes.

The full prose below covers each step in depth, plus integrations (DMS, telemetry, ERP) and deployment-model selection (Reference App vs Embedded vs API Only). Skip to the section you need.

Self-Serve Onboarding

For fast evaluation or proof-of-concept deployments, Planara includes a self-serve onboarding script that takes a single PDF and generates a complete pipeline configuration automatically.

.venv/bin/python scripts/onboard.py \
    --pdf manual.pdf \
    --manufacturer "Acme" \
    --namespace acme \
    --equipment-models "Model A, Model B"

Always specify --equipment-models during ingestion to tag documentation with the applicable equipment models. Use _global for documentation that applies across all models within the namespace (e.g., general safety procedures, shop standards). The onboard script validates equipment model metadata on every chunk and updates the equipment registry in the database.

The script runs the following stages in sequence:

1. Ingest PDF -- parse, chunk, and index the document
2. Generate prompt config -- create namespace-specific prompt templates
3. Extract maintenance ontology -- map procedures to page numbers
4. Detect part number patterns -- identify the manufacturer's part numbering scheme
5. Generate domain ontology -- build synonym mappings and fault code associations using AI
6. Generate CKL trigger config -- identify applicable safety standards and trigger terms
7. Auto-generate eval queries -- create test questions from the document content
8. Draft deterministic paths -- extract fault code lookup tables from DTC chapters
9. Extract diagnostic templates -- identify troubleshooting sections and generate structured diagnostic decision trees. Templates are created as drafts and can be reviewed before activation. Once active, they improve over time based on technician usage — successful diagnoses increase template confidence, unsuccessful ones flag templates for review.
10. Run validation eval -- verify the generated configuration produces correct answers
11. Generate failure-mode ontology -- common faults, causes, and symptoms from the corpus
12. Whole-asset overview -- a cited orientation of the asset and its major subsystems (multi-machine assets get a per-machine + facility roll-up hierarchy)
13. Suggestion chips -- corpus-grounded starter questions, per role, that never reference equipment outside the corpus
14. Readiness gate (self-certification) -- probes the live engine across three classes (GROUNDING: each machine answers with citations; SAFETY: a described hazard triggers the safety-stop; HONESTY: an out-of-corpus question is declined, not fabricated) and writes a verdict — ready or needs_attention with reasons — to the tenant config

After the script completes, you have a working namespace with documents ingested, ontology configured, CKL triggers set, eval queries ready for review, a whole-asset overview, corpus-grounded suggestion chips, and a readiness verdict confirming the tenant is launch-ready (or flagging what needs attention). All configuration is stored in the database and loaded at query time — no config files to manage, no redeployment needed to change settings. The readiness verdict is exposed on the tenant config API so the backoffice and SDK apps can surface it. This replaces weeks 1-2 of the manual onboarding checklist for initial setup.

Every served answer is also protected by deterministic safety gates independent of the model: an asset-state hazard stop (submersion, fire, arcing, contamination, energized work), a single-source-procedure guarantee (a procedure never blends steps from two different machines), and machine-scope persistence across a conversation. These are guarantees, not prompt suggestions.

New: Provisioning can now be done from the backoffice UI instead of the CLI. See Tenant Provisioning for the form-based workflow. The New Tenant Setup page covers the end-to-end quick start path.

When to use self-serve onboarding:

• Proof-of-concept evaluations with a single document
• Rapid vertical expansion (new manufacturer or equipment category)
• Internal testing before committing to full customer onboarding

When to use full manual onboarding:

• Production deployments requiring integration with DMS, telemetry, or ERP
• Customers with multiple document types and complex role configurations
• Deployments where domain expert review of ontology and evals is critical

1. Deployment Model Decision

The first conversation with every customer starts here. How will their technicians access Planara?

                    How will your team use Planara?
                              |
              +---------------+---------------+
              v               v               v
      Reference App     Embedded Widgets   API Only
      (our frontend)    (in your tools)    (your frontend)
              |               |               |
      Full experience   Pick & choose     Complete control
      Fastest to deploy  Medium effort     Most effort
      Branded to you    Fits existing UX   Your design

Reference App

Deploy the Planara technician dashboard as-is. Branded with the customer's colors and logo. iPad-optimized PWA that technicians add to their home screen.

Best for: Dealers and service operations that do not have existing field service software, or where the existing software is a legacy system nobody wants to touch.

What they get: Queue view, AI assessment, step-by-step procedures with safety warnings, follow-up chat, telemetry gauges, parts identification, diagram highlighting, customer status portal. Everything.

Timeline: 2-4 weeks from contract to live.

What we do: Upload their documentation, configure branding, set up roles, tune the ontology, run evals, deploy. They get a URL and a QR code for their technicians.

Embedded Widgets

Take specific Planara widgets and embed them into existing tools. The customer keeps their DMS or field service app for job management and uses Planara for intelligence — assessment, procedures, chat, safety.

Best for: Companies with existing DMS or field service apps (Lightspeed, CDK, ServiceMax) who want to add AI intelligence without replacing their current UI.

What they get: Individual widgets via iframe or web component. Each widget is self-contained and communicates with the Planara API independently.

Available widgets for embedding:

• AI Assessment (diagnosis + confidence scoring)
• Procedure Viewer (step-by-step with safety)
• Chat Panel (follow-up questions with citations)
• Safety Warnings (standalone CKL display)
• Telemetry Gauges (if telemetry integration is active)

Timeline: 4-8 weeks. Requires coordination with the customer's development team for embedding and passing context (equipment model, fault codes, work order ID).

What we do: Provide embed endpoints, coordinate on authentication handshake, configure CORS, test within their application.

Status: [PLANNED] — Widget embedding endpoints are architecturally supported but not yet packaged as a documented integration path. Reference App and API Only are production-ready today.

API Only

The customer consumes the Planara REST API directly and builds their own frontend. They get structured JSON responses — typed procedures, safety warnings, specifications, parts lists, confidence scores — and render them however they want.

Best for: Companies with development teams who want complete UI control, or OEMs building intelligence into their own dealer portal.

What they get: Full API access. Every response is structured JSON, not prose. See the Widget API documentation for response schemas.

Timeline: 8-16 weeks. Depends entirely on the customer's development velocity.

What we do: Provide API credentials, documentation, sandbox environment, and sample responses for every query type. The customer builds their own frontend. We support on the API side.

2. Integration Planning

Integrations are optional. Planara works without any external connections — the intelligence layer (assessment, procedures, chat, safety) runs entirely from ingested documentation. Integrations add context: live telemetry, work order data, parts inventory, service history.

Start without integrations. Add them when the customer sees value.

              What systems does the customer have?
                              |
     +----------+-------------+-------------- +----------+
     v          v             v               v          v
    DMS      Telemetry     Parts/ERP       Identity   Nothing
  (jobs,     (sensors,     (inventory,     (SSO,      (start
  customers) live data)    ordering)       users)     simple)

Dealer Management System (DMS)

What it provides: Work orders, customer contact info, service history, parts on order, bay assignments, technician assignments.

Common providers in marine: Lightspeed EVO, CDK Marine, DockMaster, MarineMax Dealer Solutions, IDS (Integrated Dealer Systems).

Integration method: REST API adapter. We build the adapter; the customer provides API credentials and sandbox access.

Data mapping:

DMS Work Order    ->    Planara Queue Job
-------------------------------------------
work_order_id     ->    job.id
vessel_name       ->    job.label
vessel_model      ->    job.sublabel
customer_name     ->    job.customer
complaint_text    ->    job.complaint
engine_model      ->    job.equipment
engine_hours      ->    job.hours
fault_codes[]     ->    job.faultCode
bay_assignment    ->    job.bay
parts_status      ->    job.partsStatus

What we need from them:

• API documentation (REST endpoints, authentication method)
• Sandbox credentials (not production — we develop against sandbox first)
• Sample data export (5-10 work orders with realistic content)
• Field mapping review (their field names mapped to ours, confirmed by their team)

Timeline: 2-4 weeks for providers we have built adapters for (Lightspeed). 4-6 weeks for new providers.

What happens without it: Technicians use the "New Job" sheet to manually enter equipment, complaint, and fault codes. The Queue view shows manually-created jobs. All intelligence features (assessment, procedures, chat, safety) work identically.

Telemetry Source

What it provides: Live engine data — RPM, coolant temperature, oil pressure, battery voltage, engine hours, fuel level. Also fault code history and event logs.

Common providers in marine: Siren Marine, Nautic-On, Mercury VesselView, Yamaha CL7, NMEA 2000 gateway devices.

Integration method: REST API polling (we pull on interval) or webhook push (they push on event). Polling is simpler; webhooks are more responsive.

Data mapping:

Telemetry Feed    ->    Planara Telemetry Widget
------------------------------------------------
engine_rpm        ->    gauge: RPM
coolant_temp      ->    gauge: Coolant Temp
oil_pressure      ->    gauge: Oil Pressure
battery_voltage   ->    gauge: Battery
engine_hours      ->    gauge: Engine Hours
fuel_level        ->    gauge: Fuel Level
fault_events[]    ->    event timeline chart

What we need from them:

• API documentation (endpoints, authentication, data format)
• Device IDs for their fleet (which devices map to which equipment)
• Sample payload (one real telemetry reading so we can verify field mapping)
• Event types (what severity levels they use, how they classify alerts)

Timeline: 1-2 weeks. Telemetry APIs tend to be simpler than DMS APIs.

What happens without it: Telemetry widgets show "No telemetry connected" with a prompt to set up the integration. All other features work normally. The AI assessment and procedures do not depend on telemetry — it enriches them when available but is not required.

Parts / ERP

What it provides: Parts inventory, pricing, bin locations, order status, availability across locations.

Common providers: SAP, Oracle, NetSuite, QuickBooks, or the parts module within the DMS.

Integration method: REST API adapter, same pattern as DMS.

Data mapping:

ERP Parts Data    ->    Planara Parts Widget
--------------------------------------------
part_number       ->    part.partNumber
description       ->    part.description
qty_on_hand       ->    part.quantity
bin_location      ->    part.binLocation
unit_cost         ->    part.unitCost
order_status      ->    part.status

Timeline: 2-3 weeks. Often bundled with the DMS integration if the DMS includes a parts module.

What happens without it: Parts referenced in procedures show part numbers and descriptions from the service manual. No live inventory or pricing data. Technicians cross-reference their parts system manually — the same workflow they have today.

Identity (SSO)

What it provides: Single sign-on, user provisioning, role assignment from the customer's identity provider.

Common providers: Azure AD, Okta, Google Workspace, Auth0.

Integration method: SAML or OIDC federation with the authentication provider.

Status: [PLANNED] — Not built yet. Current authentication uses passwordless magic link (email-based). Works well for small-to-medium deployments. SSO becomes important for enterprise customers with 50+ users and existing identity governance.

Timeline: TBD. Will be prioritized based on customer demand.

What happens without it: Technicians log in via magic link (enter email, click link, done). Admin manages users in the backoffice Team page. Role assignment is manual. This works for most deployments.

No Integrations (Start Simple)

This is the recommended starting point for most customers. Get the intelligence layer working first, prove value, then add integrations.

What works without any integrations:

• AI Assessment — full diagnosis from fault codes and symptoms
• Step-by-step procedures with safety warnings
• Follow-up chat with citations
• Parts identification from service manual references
• Diagram highlighting
• Safety enrichment (CKL)
• Eval system and quality monitoring
• Backoffice for content management

What requires integrations to show real data:

• Queue view (shows demo data or manually-created jobs without DMS)
• Telemetry gauges (show "not connected" without telemetry source)
• Live parts inventory and pricing (without ERP)
• Service history from prior visits (without DMS)

3. Content Preparation

Content is the foundation. The quality of Planara's responses is directly proportional to the quality and completeness of the ingested documentation. Garbage in, garbage out.

              What documentation does the customer have?
                              |
     +----------+-------------+--------------+----------+
     v          v             v              v          v
  Service    Owner's       Parts         TSBs/       Training
  Manuals    Manuals       Catalogs      Bulletins   Guides
  (primary)  (secondary)   (reference)   (updates)   (optional)

Service Manuals (Primary)

The most important documents. These contain troubleshooting procedures, specifications, torque values, wiring diagrams, and disassembly/reassembly instructions.

Format: PDF. Scanned PDFs work but produce lower-quality chunks than native/digital PDFs. If the customer has both, use the digital version.

What to expect: A typical 500-page service manual produces 800-1200 chunks after ingestion. Quality score (auto-calculated during ingestion) should be above 0.7. Below 0.5 indicates poor source quality — usually scanned documents with OCR errors.

Scope: One service manual per equipment model or model family. A Yamaha F350A has its own service manual. A Yamaha F250/F300 may share one manual covering both models.

Typical volume: 1-3 service manuals per equipment model. Large manufacturers may have 10-20 across their product line.

Owner's Manuals (Secondary)

Simpler language, focused on operation, maintenance schedules, and troubleshooting basics. Used for the owner-facing role and as supplementary context for technician queries.

Format: PDF. Usually higher quality than service manuals because they are produced digitally.

What to expect: 100-200 pages, 200-400 chunks. Lower technical density than service manuals but valuable for maintenance schedules and specifications.

Parts Catalogs (Reference)

Exploded diagrams with part numbers, descriptions, and quantities. Powers the parts identification feature.

Format: PDF. Often the most challenging documents to ingest because they are primarily visual (exploded diagrams with callout numbers).

What to expect: Diagram-heavy. The ingestion pipeline extracts text annotations and part number tables. Diagrams are preserved as page images for the highlighting feature.

Technical Service Bulletins / TSBs (Updates)

Short documents (2-10 pages) that update or supersede content in the service manual. Critical for known issues, recalls, and updated procedures.

Format: PDF. Usually well-structured and high quality.

What to expect: Each TSB produces 5-20 chunks. They have outsized importance because they often contain the answer to the most common real-world problems — the issues that generate support calls.

Important: TSBs should be tagged with the equipment models they apply to during upload. This ensures they are retrieved only for relevant equipment.

Training Guides (Optional)

Manufacturer training materials, certification study guides, dealer training decks. Lower priority but can fill gaps where service manuals assume knowledge.

Format: PDF, sometimes PowerPoint converted to PDF.

What to expect: Variable quality. Training materials are often conversational rather than procedural. They supplement but do not replace service manuals.

What We Need from the Customer

1. All relevant PDFs — uploaded directly in the backoffice or sent to the Planara team for ingestion
2. Equipment model list — which models are in scope, which documents apply to which models. Each document should be tagged with its applicable equipment models during upload. Documents that apply across all models should be tagged as _global.
3. Known documentation gaps — topics where the manual is thin or missing, common questions the support desk fields that aren't well-documented
4. TSB inventory — all active TSBs, organized by equipment model

4. Configuration Checklist

This maps directly to the backoffice. Each checkbox is something that gets configured in the Planara admin interface or by the Planara team.

Week 1: Foundation
+-- [ ] Upload service manuals (Documents -> Upload)
+-- [ ] Upload owner's manuals
+-- [ ] Upload parts catalogs and TSBs
+-- [ ] Set equipment types (Equipment -> Add Type)
+-- [ ] Create fleet instances (Fleet -> Add Instance)
+-- [ ] Configure roles (Roles -> Load Templates)
+-- [ ] Set tenant branding (Settings -> Branding)
+-- [ ] Verify ingestion quality scores (Documents -> Detail)

Week 2: Intelligence Tuning
+-- [ ] Review auto-generated evals (Eval -> Review)
+-- [ ] Set evals to trial mode (toggle on pending queries)
+-- [ ] Run first trial eval suite
+-- [ ] Review trial results with domain expert
+-- [ ] Configure CKL safety standards (Compliance -> Discovery Wizard)
+-- [ ] Review ontology for domain terms (Planara team)
+-- [ ] Build fault code mappings (Planara team)
+-- [ ] Adjust confidence thresholds per role
+-- [ ] Promote passing trial evals to golden

Week 3: Integration & Testing
+-- [ ] Connect DMS (if applicable)
+-- [ ] Connect telemetry (if applicable)
+-- [ ] Configure dashboard widgets (Dashboard Config)
+-- [ ] Test with 2-3 pilot technicians
+-- [ ] Collect feedback on first 20 queries
+-- [ ] Fix retrieval misses with ontology additions
+-- [ ] Run full eval suite — compare to baseline
+-- [ ] Set eval baseline

Week 4: Launch
+-- [ ] Enable for all technicians
+-- [ ] Enable nightly eval runs (Settings -> Quality Automation)
+-- [ ] Set up adoption monitoring (Analytics -> Adoption)
+-- [ ] Configure ROI calculator values (Settings -> ROI)
+-- [ ] Schedule first review meeting (2 weeks post-launch)
+-- [ ] Provide technician quick-start guide (URL or QR code)

Week 1 Detail: Foundation

Document upload is the most critical step. Use the backoffice Documents page. Upload one document at a time. After each upload, check the ingestion status — it should complete within 2-5 minutes per document. Review the quality score and chunk count on the Document Detail page.

Equipment types define the categories of equipment the customer services. For a marine dealer: outboard engines, sterndrive, inboard, generators. Each type has its own set of applicable documents.

Fleet instances are specific pieces of equipment: "Yamaha F350A, serial 6CJ-1042867, on vessel Blue Logic." Fleet instances link equipment types to telemetry sources and service history.

Role templates come pre-configured for technician, service writer, owner, and admin. The customer may need to adjust what each role can see — for example, hiding cost information from technicians or limiting owner visibility to status-only.

Branding includes primary color, logo, and display name. Applied to the Reference App if that is the deployment model.

Week 2 Detail: Intelligence Tuning

This is where Planara becomes actually useful for the specific customer. See the Tuning Guide for the full methodology.

Auto-generated evals are created during document ingestion. The system reads the documentation and generates questions a technician would likely ask. These start in "pending" status. The customer's domain expert (a senior technician or service manager) reviews them and either approves or adjusts the expected answer.

Trial mode lets you run evals without committing them to the golden baseline. This is important — you want to iterate on the ontology and prompts before locking in what "correct" looks like.

CKL configuration uses the Standards Discovery Wizard to identify which industry safety standards apply. For marine: ABYC (electrical, fuel, propulsion), USCG (safety equipment), OSHA (shop safety). The wizard scans the ingested documentation and suggests relevant standards.

Ontology tuning bridges vocabulary gaps. When a technician asks "how do I winterize?" and the manual says "long-term storage procedure," the ontology maps one to the other. This is done by the Planara team based on retrieval miss analysis.

Week 3 Detail: Integration & Testing

Pilot technicians should be chosen carefully. Pick 2-3 technicians who represent the range: one experienced tech who will test the system hard, one mid-level tech who represents the typical user, and one junior tech who represents the target beneficiary.

First 20 queries are the most important data point. Review every response. Identify retrieval misses (the answer exists in the manual but was not retrieved), generation errors (the answer was retrieved but the response was wrong), and gaps (the answer does not exist in the documentation).

Eval baseline is set after tuning is complete. This becomes the benchmark for nightly regression checks. If a future model update or documentation change causes quality to drop below baseline, the system alerts automatically.

Week 4 Detail: Launch

Enable for all technicians means giving every technician the login URL or QR code. For Reference App deployments, this is an "Add to Home Screen" action on their iPad.

Nightly eval runs automatically test the golden query set every night and report any regressions. Results appear in the backoffice Eval Dashboard.

Adoption monitoring tracks which technicians are using the system, how often, and what they are querying. Low adoption in the first two weeks is a signal that training or UX adjustments are needed.

First review meeting should be scheduled 2 weeks after launch. Review: adoption metrics, feedback scores, most-queried topics, any retrieval misses, and technician sentiment. Adjust ontology and prompts based on findings.

5. Decision Matrix

What is included at each deployment level:

Choosing the Right Model

Choose Reference App if:

• You do not have existing field service software
• Your existing software is a legacy system you do not want to modify
• You want the fastest path to value
• Your technicians primarily use iPads in the shop

Choose Embedded if:

• You have an existing DMS or field service app that technicians already use daily
• You want AI intelligence without changing the technician's workflow
• Your development team can handle iframe or web component integration

Choose API Only if:

• You have a development team that will build and maintain a custom frontend
• You need the intelligence layer inside a product you are building
• You are an OEM embedding Planara into your own dealer portal
• You require complete control over the user experience

6. What Happens After Launch

First 30 Days

• Monitor adoption daily in the backoffice Analytics page
• Review negative feedback (thumbs-down) daily — each one is a learning opportunity
• Auto-generate eval queries from real technician questions
• Iterate on ontology based on retrieval misses
• Review technician-submitted corrections as they come in — validate and activate the good ones
• Expect 60-70% adoption in week 1, growing to 80-90% by week 4 if the first answers are good

First 90 Days

• Monthly review meetings with usage metrics, feedback analysis, and field intelligence metrics
• Ontology refinement based on accumulated query data
• TSB ingestion as new bulletins are released by the manufacturer
• Eval baseline updates as the golden query set grows
• Integration additions if starting without integrations
• Review diagnostic template performance — promote successful templates, review flagged ones
• First network resolution analysis for OEM deployments — where is the manual disagreeing with reality?

Ongoing

• Nightly eval runs catch regressions automatically
• New documentation ingested as manufacturers release updates
• Quarterly business reviews with adoption trends, ROI calculations, and field intelligence impact
• CKL standard updates as industry regulations change
• Network-wide pattern analysis for OEM deployments — field issue detection, correction clusters, resolution analytics
• Knowledge velocity tracking — how fast is the field intelligence loop capturing and applying new knowledge?

7. Common Questions

How long does document ingestion take? 2-5 minutes per document for parsing and chunking. Indexing happens automatically after parsing. A full service manual (500+ pages) takes approximately 5 minutes end to end.

What if the customer's manuals are in a language other than English? The pipeline supports English documentation today. Multi-language support is planned. For non-English markets, the customer's documentation must be in the language it was authored in — we do not translate.

Can we ingest documentation that is not PDF? PDF is the primary supported format. Word documents and HTML can be converted to PDF before ingestion. Native support for additional formats is planned.

What happens if the customer changes DMS providers? We build a new adapter for the new provider. The Planara data model does not change — only the adapter layer. Typical migration: 2-4 weeks.

How is data isolated between customers? Every customer is a separate tenant (namespace). Documents, evals, integrations, users, and analytics are fully isolated. One customer cannot see another customer's data. The multi-tenant architecture is enforced at the database level.

What about HIPAA / SOC 2 / data compliance? Planara does not hold a SOC 2 Type II report today. The certification process is planned, not started, and takes 3-6 months once begun. The underlying infrastructure providers (database, hosting, vector index, object storage, model providers) each hold SOC 2 Type II, and all customer data is encrypted at rest and in transit. Dedicated single-tenant infrastructure is available by arrangement rather than as a packaged tier. Contact us for specific compliance questions — we will tell you what is in place and what is not.