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.