Coverage map
How product docs relate to ADRs and the OKF knowledge bundle — and what is intentionally out of scope.
SolutionDesk has three documentation layers. They must not all say the same things.
| Layer | Audience | Location | Purpose |
|---|---|---|---|
| Product docs | Staff, portal users, host integrators | apps/docs (this site) | What to click, what customers see |
| ADRs | Engineers & agents making decisions | docs/adrs/ | Why we built it this way |
| OKF knowledge | Agents implementing/debugging | docs/knowledge/ | Load-bearing traps and invariants |
ADR → product docs
| ADR | Topic | Product docs | Notes |
|---|---|---|---|
| 0001 → 0009 | Staff vs end-user identities | Audiences | Superseded details stay in ADR |
| 0002 | MagicLink portal | Open portal, Host API | |
| 0003 → 0009 | Cosmos partition keys | — | Impl only (knowledge: partition-scoping) |
| 0004 + 0010 | Host SaaS API / API keys | Host SaaS API, Integrations | |
| 0005 | Zod SSOT | — | Impl only |
| 0006 → 0007 | Better-Auth Cosmos adapter | — | Impl only |
| 0008 → 0009 | Path tenancy / slug | Workspace shape, Sign-in | Product: workspace slug URLs |
| 0009 | Workspace / Company vocabulary | Workspace shape, Companies | |
| 0011 + 0013 | Ticket types & custom fields | Ticket configuration, Create ticket | |
| 0012 | Readable ticket ids | Tickets & visibility | Reference #… / YYMMDD-XXXX style ids |
| 0014 | API + SPA split | — | Architecture; not end-user UX |
| 0015 | SMTP password encryption | Integrations | Product: configure SMTP; crypto is ADR/knowledge |
| 0016 | Tenant config i18n | Languages, portal locale notes, event languages | Events translate per language on the event (decision E18), not per field |
| 0017 + 0018 | Two-tier portal, roles, company statuses | Two-tier portal, Portal roles | |
| 0019 | Staff MCP | MCP for agents, Agents & MCP | Knowledge has tool traps |
| 0020 | API under /v1 | Host SaaS API | Paths mentioned for integrators |
| 0021 | Custom domains | Integrations & domains | |
| 0022 | Company labels (portal) | Company labels | |
| 0023 + 0026 | Mentions | Mentions & watchers | |
| 0024 | Guest portals | Guest portals | Knowledge: guest-tokens |
| 0025 | Ticket watchers | Mentions & watchers, portal detail | |
| 0027 | Visibility tiers | Tickets & visibility | Knowledge: reverse-visibility for two-tier |
| 0028 | Live updates (SSE) | Live updates | Mostly invisible UX |
| 0029 | Azure service principal | — | Ops/impl only |
| 0030 | Free trial stamped on workspace creation | Sign in | Non-enforcing; knowledge: auth/workspace-trial |
| 0031 | Erasure tombstones the identity, keeps content | — | Not built — no self-service account deletion yet; Account says so |
| 0032 | Per-user notification preferences | Account, Settings overview | Switches live under Settings → Notifications; MCP exposes get_/save_notification_preferences |
| 0033 | Staff two-factor & passkeys | Sign in, Account, Settings overview | Knowledge: auth/staff-mfa |
| 0034 | Addon system (App Store) | App Store | Shipped addons: Demo tickets, Sentry. Knowledge: addons/* |
| 0035 | Ticket subtasks | Create ticket, Portal board, Request detail, MCP | Knowledge: data/ticket-subtasks (rules, completion policy, fence) |
| 0036 | Ticket templates separate from types | Ticket configuration, Create ticket, Ticket detail | Knowledge: data/ticket-templates |
| 0037 | Command/query bus in the API | — | Impl only |
| 0038 | CRM module with linkable accounts | CRM, Accounts & contacts, Deals, Activities, meetings & tasks, Import, CRM settings, MCP | Staff-only; never in portal guides. Knowledge: crm/* |
| 0039 | CRM contacts separate from portal identities | Accounts & contacts | Knowledge: crm/contacts-and-portal-users |
| 0040 | Inbound email | — | Proposed, not built |
| 0041 | Server-side CRM search | Search | Knowledge: crm/search-and-customer-card, data/global-search |
| 0043 | CRM task reminders | Activities, meetings & tasks, CRM settings | Knowledge: crm/task-reminders |
| 0044 | Multiple ticket boards | Boards, Tickets board, Ticket configuration, Integrations (“Notify me for boards”) | Portal guides unchanged: customers only ever see the customer board. Knowledge: data/board-* |
| 0045 | Background jobs queue | — | Impl only |
| 0046 | Files on CRM accounts | Accounts & contacts | Knowledge: crm/* |
| 0047 | Fixed staff roles | Members & roles, CRM, Newsletter | Knowledge: auth/* |
| 0048 | CRM duplicates and merging | Duplicates | Knowledge: crm/* |
| 0049 | Events module with public registration | Events, Registration, On your website, Event settings, Host API | Public event pages run on the events site (apps/events); cover and gallery images, languages, website announcement, MCP tools. Knowledge: events/* |
| 0050 | Newsletter module | Newsletter, Newsletter settings | Stage 1 complete: lists, sign-up pages with double opt-in, preferences page, campaigns, tracking, the CRM link, the event checkbox, retention and the access-request download. The integration API (stage 2) isn't built. Knowledge: newsletter/* |
Knowledge bundle → product docs
Most of docs/knowledge/ is agent debugging and should not be rewritten as product tutorials.
| Knowledge area | Product surface? |
|---|---|
| data/* (pagination, partitions, config keys) | No — agents only |
| visibility/* | Partial — user-facing summary in concepts; reverse visibility in two-tier guide |
| auth/* | Partial — audiences + guest portals; guard details stay knowledge |
| portal/* | Yes — portal guide + two-tier + roles |
| realtime/* | Brief product note only |
| mcp/* | Product: connect + tools; knowledge: announce, leaks, architecture |
| addons/* | Partial — App Store covers install and setup; webhooks and the registry stay knowledge |
| crm/* | Yes — team guide CRM pages (click paths); partition keys, lock docs, claims and reminder index stay knowledge |
| events/* | Yes — team guide Events pages (click paths); revision check, route layout and time-zone helpers stay knowledge |
| newsletter/* | Yes — team guide Newsletter pages; pacing, job and hashing details stay knowledge |
| jobs/* | No |
| notifications/* | Product: SMTP settings + watchers/mentions UX |
| attachments/* | Product: attach/download in ticket flows |
| testing/* | No |
Deliberately omitted from product docs
- Cosmos / partition keys / pagination drain
- Zod as SSOT, package layout, webpack
- Service principal and connection strings
- Vitest Nest patterns
- MCP announce interceptor internals
When in doubt: if a customer or staff user never sees it in the UI, it belongs in ADR or knowledge, not here.