Decisions

Decision log (ADR-style) for this initiative.

ADR-001 — Board links: dashboard-root paths + render-time resolution

Status: Proposed (implement in dashboard-linking-v1)

Context

Cloud maps query string → dashboard variables; dft serve maps /{path} → {path}.yml under the project.
Authors should use normal Markdown URLs rooted at a logical dashboard namespace (e.g. /zendesk/tickets/list?status=open), not type storage prefixes like faces/ in the common case.
Browsers resolve relative URLs against the page URL (Suite dashboard route), not the repo—so we rewrite at render time.
No frontmatter slug / url_path overrides in v1: move the file to change the URL.

Decision

Author syntax: root-relative paths from the dashboard URL root (e.g. /zendesk/tickets/detail?id=…); ../ / ./ relative to current board’s slug directory after the same mapping.
Resolver maps author path → storage slug (e.g. faces/zendesk/tickets/detail) consistently for serve and Cloud.
Strip optional .md / .yml / .yaml suffixes when resolving (author sugar).
Do not rewrite http:, https:, mailto:.
List / detail (and similar) are naming conventions at the path level (e.g. …/list, …/detail); no required metadata in v1.

Branch

Merge branch from the current Cloud request into outbound links when the link omits it (details in implementation).

Status: Accepted — deferred (M5 task)

Context

Optional YAML (canonical_for, entity + role) could help agents pick a default drill board without a slug.
Adds duplication vs file paths and validation cost.

Decision

V1 / M2: Do not implement entity-registry or canonical-board metadata.
Prefer conventions: recognizable paths (e.g. /zendesk/tickets/list, /zendesk/tickets/detail?…) plus search / explicit links for agents.
Revisit in M5 only if we have evidence (e.g. agent or UX pain) that conventions are insufficient.

Consequences