Mandrel user guide

Getting started

• Super admins manage cross-tenant settings (where enabled), platform-wide safeguards, escalation contacts, and onboarding org templates. Look for superseded routes labelled “Super”.
• Org admins / owners configure workspaces: collections navigation, integrations, auditing exports, backups, SSO posture when licensed, quotas, invitations, destructive actions.
• End contributors operate within assigned scopes—opening assigned collections forms, reacting to validations, dashboards, collaborating with references/children when granted.

First-login security checklist

• Immediately replace default/expired seeded passwords mandated by onboarding mail.
• Select “stay signed in” only on managed hardware; admins may disable via policy.
• Confirm active organization slug (top selectors) aligns with tenancy you intend to mutate.
• Review Notifications + Settings → Security surfaces for PATs/password hygiene once enabled.

Orientation cues

Sidebar (or dual-navbar mode) aggregates navigation entries configured per tenant. Settings hub swaps layout to focus purely on personalization, integrations, accessibility, appearance, APIs, notifications, navigation exports, accessibility toggles referenced from your admin console.

Core capabilities

• Collections hold schema-backed tables with versioning/soft-delete arcs.
• Forms collect structured payloads with validations & sectioning aiding long intake flows.
• Permissions align to CRUD bits per-collection with optional automation hooks.
• Navigation customization keeps frequently used collections/front-door dashboards surfaced for operators.
• Validation: server-side authoritative checks reconcile with localized inline messages.
• Security features include audit logs (where entitlement applies), SSO hooks, granular API tokens surfaces, hashed credentials, brute-force damping.

Collections & field archetypes

Every collection manifests fields with typing (text/select/numeric/date/boolean/geo/json/etc.), validations, uniqueness rules, masking for sensitive subsets, and optional references pointing to sibling collections powering relational integrity.

• Parent-child trees mirror operational hierarchies; child rows inherit ancestry filters respecting permission gates.
• Reference lookups maintain referential breadcrumbs in detail drawers for cross-navigation.
• Calculated/read-only synthesized fields summarize rollups guarded by deterministic expressions.

Form builder playbook

1. Establish sections mirroring departmental responsibilities (Identify → Assess → Resolve).
2. Split overwhelming flows into wizard-like tabs sparingly once mobile ergonomics degrade.
3. Group repeated elements (address blocks, consent blocks) enabling uniform validation messages.
4. Wire workflow triggers AFTER stabilizing validations—prevent half-baked payloads hitting downstream systems.
5. Best practice: keep AI-generated helper text human-reviewable behind staging toggles.

Users & roles permission matrix

Exact bitmasking aligns to organization-specific matrices—export from admin documentation when customizing.

Working with records

• CRUD entry points reside in contextual toolbars/list rows/drawers; optimistic UI defers ultimately to server validations.
• Audit overlays—when entitlement exists—expose actor, deltas, impersonation disclaimers behind admin filters.
• Search honours tokenization per column indexing; fuzzy toggles contingent on infra scale guidance.
• Sorting & pagination default to indexed columns; watchers should avoid pinning extremely wide sorts on huge tables concurrently.

Advanced topics

AI assistant

• Capable of surfacing summarized records, prepping checklist prose, iterating on filters when tools enabled.
• Cannot bypass RBAC—invisible records remain inaccessible through assistant surfaces.
• Quota messaging surfaces when exhausting daily allotment; escalate to admins for reallocations/licensing.

Relationships/hierarchy drilling

Drill from parent KPIs into child anomalies using filtered list links; breadcrumbs reflect permission boundaries trimming inaccessible branches gracefully.

Reporting & analytics

Dashboard widgets & analytic SQL executions honor same permission scaffolding—sharing screenshots externally may violate confidentiality; confirm scope before circulating metrics.

Help & troubleshooting (FAQ-flavored)

Access denied on collection

Administrator likely trimmed role intersections—inspect Settings → Roles; confirm active org context.

Persistent validation errors

Note server messages near fields; watchers must resolve cross-field formulas before save.

Need password rotation

Use Forgot password handshake or enforced admin-reset policies for corporate directories.

Exports missing?

Certain integrations require auditing entitlements enabled; escalate to admins with rationale.

Hidden buttons

Feature flags conceal modules—consult admins about pending pilot toggles aligned to compliance.

Quick reference & keyboard hygiene

• Ctrl/Cmd + K (when command palette surfaced) primes global search—confirm parity with localized docs.
• ? may reveal contextual overlays where implemented—fallback to header help links.
• Action cheat sheet: create record (contextual FAB), duplicate row (ellipsis), open audit drawer (shield icon gated), escalate automation failure (toast deep link).

Contributions welcome via internal ticketing—reference doc section IDs speeds triage (“docs#getting-started”, etc.).