User manual¶
End-user / admin documentation for REBIM. NOT a developer reference
— that's [devdocs/]. NOT a planning corpus — those live at the repo
root as <NAME>-PLAN.md files (and are deleted once the work ships
or the plan is abandoned).
Audience¶
Technical-curious end users + tenant admins. Readers who understand "workflow", "transition", "tenancy", "role" as concepts but want the concrete rules: who sees what, when, why; what each tab does; what each setting changes.
Not aimed at:
- Non-technical first-time users — they get the in-app Shepherd
product tour (
templates/default/dashboard/dashboard_tour.html). - Developers —
devdocs/covers the codebase, app structure, deployment, integrations. - Ops —
devdocs/UPGRADE.md,devdocs/DEPLOYMENT_NOTES.md.
Naming convention¶
<NOUN>.md (uppercase, single-word topic where possible). Mirrors how
the dev planning files are named (<NAME>-PLAN.md at repo root) so
anyone moving between corpora knows the shape on sight.
Contents¶
Each file aims to be standalone-readable + cross-linked to its relevant siblings. The set grows as topics get written. Dangling links (to files not yet written) are intentional placeholders, not bugs.
| File | Status | Topic |
|---|---|---|
| VISIBILITY | v1 written 2026-05-22 | The "I can't see X" landing page. Five visibility layers, troubleshooting decision tree, symptom catalogue, worked examples. Start here for any "why can't user X see Y" question. |
| TENANCY | v1 written 2026-05-22 | Multi-tenant model, config tenant vs data tenants convention, "missing config tenant" failure mode, troubleshooting |
| PERMISSIONS | Refocused 2026-05-22 (CRUD-only after the visibility/permissions split) | Two-layer model (Django perms + instance gates), users/groups/seed_groups, admin panel access, per-module edit/delete gates |
| NOTIFICATIONS | Expanded 2026-05-22 (covers all four surfaces) | The LivefeedNotification model + email queue; when notifications fire (document / event / transmittal / @mention / bellicon / subscriber paths); the activity + mention panels; bell icons on rows; document subscriptions; discussion threads + paperclip indicator; awareness labels (BYOP-era); admin controls (DISABLE_, notify_ per transition, mention From override) |
| SCHEDULER | v1 written 2026-05-22 | Scheduled recurring workflow events — calendar vs counter recurrence modes, the daily cron + SCHEDULER_LOOKAHEAD_DAYS, what happens when a schedule fires, Apply Now, permissions (project_admin + SCHEDULE CRUD), the same cron's compliance + FRA report passes |
| ROLES | v1 written 2026-05-22 | Workflow event visibility by role — disciplines, transition role categories (transition / readonly / commentonly / any), role_leader / project_admin flags, from-state-not-to-state semantic, requires_role_leader |
| PROJECTS | v1 written 2026-05-22 | Project membership (layer 2), data sources (layer 3), per-project taxonomies (systems/levels/spaces), project lifecycle + settings, tabs |
| WORKFLOWS | v1 written 2026-05-22 | Workflow definitions vs events, statuses + transitions, event types (Task/Issue/Planned/Attachment/Comment/Pin/IoT), date auto-setting, layer-5 completion gating + check-out lock, FRA flag, the workflow designer |
| TRANSMITTALS | v1 written 2026-06-02 | The Transmittals tab — formal document issue: subject/message, version selection (include Active / Active+Previous / All), distribution lists (individuals + groups expanded at send), acknowledgement, recall, document "bakes" (issued-version snapshots), CSV export, visibility (tenancy + project, no roles) |
| CONTACTS | v1 written 2026-05-22 | Contact vs User vs ProjectPeople distinction, fields, CREATE/EDIT auto-populate semantics, the email-routing caveat, companies + affiliations, troubleshooting |
| EDMS | v1 written 2026-05-22 | Documents, revisions, check-out / check-in semantics, stamps, subscribers, federation, tools (markup/viewer/3D) integration, document status vs workflow status, compliance flag + second tab, sequences, custom fields |
| EXPLORER | v1 written 2026-06-03 | The Explorer document tool (not a project tab) — launched on a document: Objects tab (3D model element tree + viewer binding, federation, IFC conversion) and Events tab (the doc's Tasks/Issues/Pins/Transmittals, parent-only); creating/transitioning/commenting/pinning from Explorer; check-out lock + role visibility; project-wide (non-chunked) data feeds |
| ACTIONS | v1 written 2026-05-22 | Cross-cutting kebab-menu reference — every action across EDMS / Workflows / Transmittals / People / Contacts / Scheduler, what each does, when it's visible (check-out interaction, compliance mode, role gates), "I don't see an action I expect" troubleshooting |
| COMPANIES | v1 written 2026-05-22 | DirectoryCompany model + [CODE] Name display convention, where companies surface (primary FK / affiliations / document revision contractor), modify-contractor bulk action, merging companies (manual flow — no built-in action) |
| PEOPLE | v1 written 2026-05-22 | Router doc for the People tab — column list, "what do you want to do?" intent map into PROJECTS / CONTACTS / ROLES / etc., tab-specific troubleshooting. Closes the People-tab discoverability gap. |
| FRA | v1 written 2026-05-22 | Fire Risk Assessment workflows — the is_fra flag, baked WorkflowFraReport monthly snapshots, the FRA dashboard surfaces, exclude_from_fra_baked_reports, UserProfile.show_fra visibility gate |
| DASHBOARD | v1 written 2026-05-22 | The dashboard's two modes (cross-project + per-project), the cross-project reports (Home / Your Workflows / All Workflows / Compliance / FRA), persistent surfaces (activity + mention panels, header), product tour entry, refresh behaviour |
Relationship to the in-app product tour¶
The Shepherd-based product tour
(templates/default/dashboard/dashboard_tour.html) is the first-time
onboarding surface — short, attached to specific UI elements, gated
on the userprofile.tour preference. The manual here is the
reference surface — readable end-to-end or by topic, lives outside
the app.
These two corpora are separate for now. The tour is hand-coded JavaScript; the manual is MD. There's no automated content sharing between them — that would be a meaningful refactor (parse MD headings → Shepherd step list, resolve attachTo selectors, etc.) and is deliberately deferred until the manual grows large enough to make duplication actively painful.
Editing¶
- One topic per file. Split if a file passes ~300 lines.
- Cross-link liberally — siblings via
[NAME](NAME.md). - Lead with the concept, then the rules, then the edge cases. Avoid source-code references where possible; when unavoidable, mark them clearly as developer-facing (e.g. "For developers: see apps/x/y.py").
- Updated when behaviour changes — same PR as the code change.