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 | |
| 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 |
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 |
| 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.