Skip to main content

Docs ↔ Product Contract

This page summarizes the canonical contract defined in zeno-specs/02_CORE/ZENO_DOCS_PRODUCT_CONTRACT.md.

Docs Base URL​

Canonical (production): https://docs.zeno-cy.com/

Docs → Product Links​

Docs can deep-link into product screens using stable routes, optional query actions, and optional UI hash anchors.

Stable routes

  • Example: https://zeno-cy.com/documents/registry

Query actions (?action=)

  • Format: ?action=<ACTION_ID>&target=<TARGET_ID>&step=<STEP_ID>&from=docs
  • Unknown action: no-op (page opens normally) and the product may show a toast.
  • Actions must be safe/idempotent: they open UI state (modal/focus/highlight) and never bypass permissions.

Examples:

  • https://zeno-cy.com/documents/registry?action=upload
  • https://zeno-cy.com/settings/storage?action=select-primary-folder&from=docs

UI element hash anchors (#ui-anchor-id)

  • Example: https://zeno-cy.com/settings/storage#primary-folder-select

Product → Docs Links​

Product UI should link to stable doc routes plus explicit anchors for exact paragraphs/sections.

Examples:

  • /docs/documents/registry#registry-upload
  • /docs/privacy-security/local-first#local-first

Recommended placements:

  • Tooltips ("What is this?")
  • Empty states ("Learn more")
  • Error states ("How to fix this?")

Naming Conventions​

From the SoT contract:

  • Action IDs: kebab-case (example: select-primary-folder)
  • UI anchors: kebab-case (example: primary-folder-select)
  • Doc anchors: kebab-case (example: registry-upload)
  • Help keys: dot-separated lower-case (example: help.documents.registry.upload)

Optional Analytics​

If enabled, analytics must be non-sensitive (no filenames, document contents, paths, PII, or tokens). Example events:

  • help_opened (help key + screen)
  • action_link_opened (action + handled/unhandled)

Security & Privacy Rules​

  • Never embed tokens in URLs.
  • Links/actions must not bypass permissions.
  • Help links must not leak tenant-scoped or sensitive data.