marulaDocs
Documentation menu
These are pre-release docs from the main branch.

Admin how-to guides

Each how-to guide gives you a direct checklist for one specific job in Marula. If you are brand new and want a guided walkthrough from start to finish, begin with Tutorials. If you want the reasoning behind a product rule, read Explanation. For field-level schemas and endpoints, see Reference.

Every guide lists its target Audience (admin, staff, or both) right under the title so you know whether it requires administrator settings access or is part of everyday service desk work.

Not sure which guide you need? Start here routes by role, and Troubleshooting starts from a symptom when something is broken rather than unconfigured.

Daily guides for technicians and service desk staff

  • Work a ticket — Open a ticket from your morning queue, run the timer, post internal or customer-visible notes, and send your hours to approvals.
  • Dispatch from the board — See technician capacity across the day, drag unassigned tickets onto open calendar slots, and resolve scheduling conflicts.
  • Run a service day from the phone — Accept scheduled site visits, clock in and out on tickets, log mileage between stops, and work offline when you lose signal in a server room.
  • Work a day pack — Review the tools and parts you need for today's scheduled stops before your van leaves the lot.
  • Check out tools and use parts on site — Check out tool kits, record parts used on a ticket from your phone, and return equipment when the job wraps up.
  • Move stock and check out tools in the field — Scan barcodes and QR tags with your phone camera, transfer parts between your van and the stockroom, and confirm incoming shipments.
  • Use the Marula mobile app — Install the iOS or Android build, sign in with Face ID or Touch ID, and see how offline changes sync back to the office.
  • Run stock and use parts — Receive inventory, consume or ship parts directly from a ticket, transfer stock between locations, and set low-stock reorder alerts.
  • Check tools out, and run client loans — Track who has which serialized tool right now, check kits back in, and manage hardware loaned or leased to clients.
  • Scan barcodes and QR codes — Use a USB barcode scanner or keyboard on tickets, purchase orders, and stock screens without losing focus in your open form.
  • Log billable time with categories — Pick the right work category when logging hours and record a required reason whenever work is marked non-billable.
  • Use reply snippets — Insert canned responses into ticket replies with customer and ticket details filled in automatically.
  • Sign your own email — Set up your personal greeting and email signature for ticket replies.
  • Use multiple windows — Pop the dispatch board, stock lookup, or active tickets into separate windows across multiple monitors.
  • Use the keyboard shortcuts — Hold Alt to see available shortcuts on any screen, press ? for the full cheat sheet, or turn shortcuts off.
  • Use Marula with a keyboard, a screen reader, and themes — Switch between light and dark or high-contrast themes, and navigate with a screen reader or keyboard alone.
  • Get help inside Marula — Open the contextual ? help drawer on any page and manage interactive feature tours.

Guides for client portal users

  • Portal client-side tasks — Sign in to the client portal to submit support requests, view invoices, read help articles, and book appointment times.
  • Approve or decline a quote — Review line items and expiration dates on a sent quote and record your approval or decline reason.

Billing and purchasing guides (office managers and bookkeepers)

  • Price a service contract — Set up recurring retainers, time-and-materials rate cards, prepaid hour blocks, not-to-exceed caps, minimums, annual escalators, change orders, and service credits.
  • Bill project work — Link a project to a client contract, track phase budget burn, release completed milestones into invoice runs, and log project hours without creating a dummy ticket.
  • Verify a billing period — Review every logged hour in a billing window, categorize or write down entries with a recorded reason, and sign off before issuing invoices.
  • Buy: vendors, purchase orders, receiving, bills — Create vendor records, issue purchase orders, scan arriving goods into stock, and post vendor bills against project budgets.
  • Record FX rates & read reconciliation — Add exchange rates to the append-only rate book and review multi-currency totals by line type.

Workspace setup and administration guides (admins and service desk leads)

AI, plugins, API, and self-hosting guides (admins and developers)

  • Manage AI access — Control the master AI switch, grant specific AI helpers to individual roles, and set usage caps.
  • Bring up AI with your own API keys — Make the six AI settings decisions in the order that makes the first live call work, with the refusal naming the step you skipped when you get the order wrong.
  • Run transcription and embeddings on your own hardware — Run Whisper voice transcription and 768-dimension vector search locally with Ollama so no data leaves your network.
  • Change the embedding model — Pick a tier or a named model, read the capacity refusal, and watch the resumable re-index that follows a switch.
  • Choose the retrieval mode — Run the exact scan, pgvector's iterative HNSW walk, or VectorChord's prefiltered index, and read the refusal when the database cannot run your choice.
  • Configure the plugin consent flow — Install digest-verified plugins and review capability permissions before enabling them.
  • Extend Marula with plugin surfaces — Register declarative dashboard widgets, automation triggers, read nodes, action steps, and custom field validators.
  • Write and build a plugin — Take a handler from an empty crate to a bundle an admin can install: the module contract, the manifest, the build step, the signing statement, and the audit row that tells you what happened.
  • Manage API keys — Create narrowly scoped bearer tokens for external scripts and rotate keys without downtime.
  • Call the API — Authenticate, read paged collections, handle optimistic write envelopes, and use @marula-core/sdk.
  • Report against the read model — Connect your BI tool or SQL client to the stable ops.v1_* reporting views.
  • Watch your self-hosted services — Check container health probes, inspect ClamAV email quarantines, and link out to Grafana or Uptime Kuma.
  • Run the local demo stack — Boot a seeded demo on your own machine with one command, including the BYOK checklist and the desktop alternative that needs no Docker.
  • Upgrade to the latest release — Run marula upgrade --check, back up PostgreSQL, and upgrade safely within the N-2 support window.
  • Also see the full Reference section for self-hosting runbooks and schema catalogs.