Expand handbook structure for department and shared SOPs

Objective

  • Expand Attik handbook spaces so SOPs, training, and shared reference content can be organized by department and at a broader organizational level (not only per-instance office vs inspector).
  • Support department handbook spaces for teams such as Growth and Client Success.
  • Support handbook permissions for manager-only SOPs within departments.
  • Support a regional or LP-level handbook for onboarding, training, and universal content shared across brands.

Background

  • Operations and leadership need department-specific runbooks and training without overloading the generic office or inspector libraries.
  • Today the handbook is built as two fixed collections per company, not arbitrary department or regional spaces:
  • Office Help Docs — route /handbook/office, list: 'help-docs' on helpdoc records.
  • Inspector Handbook — route /handbook/inspector, list: 'handbook' on helpdoc records.
  • Help documents are company-scoped (_companyId on helpDocSchema.ts); API lists filter by res.locals.company._id in helpdoc.ts. There is no cross-instance or LP-wide handbook today.
  • Docs use an optional free-text category field grouped in the UI (HelpDocCategory.tsx) — categories are not department spaces, permissions, or navigation roots.
  • Access is controlled by membership permissions (handbook, handbook-office, handbook-inspector, handbook-admin in permissionsData.ts), not manager-only or per-department ACLs on individual docs.
  • Playbook (/playbook, playbook/[[...title]]/page.tsx) is a separate strategic chapter experience and does not replace operational department SOP storage in handbook.
  • A regional/LP shared library may overlap conceptually with cross-instance platform work (e.g. ATT-1770 unified workspace); decision needed whether LP handbook is same-company multi-space vs true cross-tenant content.

Scope

Backend

  • attik-backend/src/models/helpDocSchema.ts — today: title, category, list, status, _companyId; no department, space, or doc-level audience fields.
  • attik-backend/src/routes/helpdoc.ts — CRUD and list by _companyId + list + status; search path also scopes to active company.
  • In scope: model and API support for additional handbook spaces (department, regional/LP — decision needed on schema), and finer-grained read/edit rules (e.g. manager-only SOPs within a department).
  • AI sync (syncHelpdocsToAIChunks.ts) indexes handbook URLs — decision needed how new spaces affect embeddings paths.

Frontend

  • attik-frontend/src/app/tools/handbook/[[...id]]/page.tsx — routes limited to office and inspector; redirects based on handbook-office / handbook-inspector permissions.
  • navButtons.tsx — Company Handbook nav shows Office Help Docs, Inspector Handbook, Service Matrix; no department or LP entries today.
  • HelpDocForm.tsx, DocEditor.tsx, DraftSheets.tsx — create/edit flows assume office or inspector slug; category picker is a string field, not space membership.
  • In scope: navigation and handbook shell for new spaces (Growth, Client Success, regional/LP), listing/filtering docs per space, and UI that respects manager-only visibility rules once backend supports them.

Permissions & admin

  • Extend or add permissions beyond handbook-admin if spaces need distinct edit vs read audiences (decision needed: new permission keys vs doc-level ACL).
  • Decision needed: who configures department/LP spaces (handbook-admin only vs settings-admin / instance management).

Out of scope (unless added explicitly)

  • Replacing Playbook content or merging Playbook into handbook.
  • Client-facing help center articles (internal handbook only unless product says otherwise).
  • Full cross-instance tools shell (see ATT-1770) — only the handbook content-sharing slice may relate.

References

  • attik-backend/src/util/data/permissionsData.ts (handbook permission category)
  • attik-frontend/src/util/data/navButtons.tsx
  • Help center: help-center-articles/company-handbook-office-and-inspector-docs.md, help-center-articles/user-permissions-reference.md (Handbook section)
  • Related (cross-instance UX, if LP handbook spans brands): ATT-1770 — Unified workspace

Please authenticate to join the conversation.

Upvoters
Status

Planned

Board
🏠

Main App

Date

10 days ago

Author

Linear

Subscribe to post

Get notified by email when there are changes.