feat(company-os): a handbook that explains every role, workflow and process, onboards everyone, and scopes to each role on a need-to-know basis #18431

Part of #18237. Design: Refined UI mockup Handbook (Company OS › Organization › Handbook); draft content written alongside the design. Builds on the role → workflow → process model in #18390.

Owner direction (2026-10-12)

• The handbook is an employee handbook that onboards everyone, people and agents.
• It always explains every role, workflow and process.
• It adapts to every role on a need-to-know basis.

What it is

• Company chapters: welcome, how we are organised, the three lines for AI (feat(automation): three AI lines per tool action — autonomous, AI drafts and a person sends, never touches — and a four-move automation setup #18430), how work flows, rules everyone follows, security and data, communication, money, changing the handbook. Each has an owner role, a version and an "applies to" scope.
• Generated reference pages — one per role, workflow, process and meta skill, built from the company model:
  • From the company model — updates itself: holders, reports-to, triggers, steps written out from the workflow graph ("If all checks pass … otherwise …", "If it fails: retry 2× then …"), AI lines, skills, routines, tools.
  • Explanation — written by the owner role: purpose and how-to prose; changes go through Approvals.
• Coverage: every role, workflow and process gets a page automatically; one without an explanation is flagged "Needs an explanation".
• Onboarding path per role: company chapters → the role's workflows → its processes. Assigned when an actor takes the role; people confirm "Read and agreed", agents load the pages.
• Need to know: each actor sees the chapters that apply to them, their roles' pages, those roles' workflows and processes, and the roles they work with by name and purpose only. Pages outside scope show as locked names. Founder & CEO and a View whole handbook permission see everything.

Acceptance criteria

• Generated pages for every role, workflow, process and meta skill, kept in sync with the model (no manual copy)
• Owner-written explanation per page; edits are suggested and published only after the owner role approves (AI drafts, a person sends)
• Coverage report: pages without an explanation are listed
• Onboarding path per role, assigned on role grant; read confirmations for people; agents receive their scoped pages as standing instructions
• Need-to-know scoping enforced server-side (not only hidden in the UI); "View whole handbook" permission on Roles
• Handbook content searchable in Knowledge and chat, within the reader's scope

Needs a decision

• Who a role "works with" (hand-offs) is not in the model yet; the mockup uses a sample map. Define it, or derive it from workflows.

Generated by Claude Code