_package-facts/ — the annotated package definition

This folder is Layer 1 of the product documentation system: the authoritative, machine-readable picture of what is in each package version, plus the docs-side annotations that give those objects and fields human meaning. The seven guides and the doc agent both read from here.

Two kinds of file

Kind	Files	Source of truth	Edit by hand?
Generated facts	clientverse-core-<version>.json, clientverse-modules-<version>.json, catalog.json, sync-report.md, annotation-backlog.md	clientverse/cv-crm (synced)	No — re-run sync.py; see sync.md
Authored annotations	objects/<module>.yaml (dispatch, whitespace, ai, analytics, core-key)	Written here (hybrid)	Yes — this is the work
Asana harvest	asana-feature-index.md	Asana CV Roadmap (point-in-time)	Re-harvest as roadmap evolves

Authority & reconciliation

• Package / module membership is authoritative from the synced facts (derived from each object's folder path in cv-crm). Both Core (1.1.6) and Modules (0.3.0) objects come from main — what customers can actually install (ADR-0009). A Modules object's module (dispatch / whitespace / ai / general) is its folder under packages/modules/force-app/.
• main, not develop. develop carries ~9 more Core objects, ~210 more fields and the unreleased AI MCP Chat. Facts sourced there would have the guides documenting features absent from every shipped package. Cross-check develop with --out to a scratch dir; never publish it.
• Module status is derived, never hand-maintained. sync.py computes shipped / foundation / not-present from what each module folder actually contains. The old hardcoded map went stale — ai stayed "placeholder" across two releases. shipped requires a user-reachable surface (custom object, LWC, tab, or trigger), not merely Apex: released ai is 3 provider-interface classes and one __mdt, so it derives as foundation.
• Asana Implementation Layer is a cross-check, not an override. Where it disagrees with the folder-derived package, flag it — don't silently change the facts.
• Object/field meaning lives in the authored objects/*.yaml because the Salesforce metadata is barely annotated today (see sync-report.md). These descriptions are also the draft text for backfilling <description>/<inlineHelpText> into the SF source later (tracked in annotation-backlog.md).

The annotation catalog (objects/<module>.yaml)

Grouped one file per module (dispatch.yaml, whitespace.yaml, ai.yaml, analytics.yaml) plus core-key.yaml for the priority Core objects — far more practical than 150 single-object files, and still machine-readable. Each file has a module header and an objects: list. Structural fields (package, module, kind, fields) mirror catalog.json; the authored fields (description, data_source, audience, per-field purpose) are what we add. annotation_status: drafted | stub.

api_name: Dispatch_Definition__c
label: Dispatch Definition
package: modules            # authoritative (folder-derived)
module: dispatch            # authoritative (folder-derived)
applies_to: [modules]
data_source: User-entered   # authored (seed from Data Dictionary v3.0 "Populated By")
description: >              # authored
  Defines a scheduled notification/digest — its audience, content query, and delivery channel.
audience: [admins]
annotation_status: drafted
fields:
  - api_name: Schedule_Cron__c
    label: Schedule
    type: Text
    description: Cron expression controlling when the dispatch runs.

v1 authoring scope: all 18 Modules objects + the Core objects the guides reference + the objects already covered by Data Dictionary v3.0. Everything else stays a stub and is listed in annotation-backlog.md.

See also

• ../_conventions.md — Core/Modules labeling + guide frontmatter.
• ../../data-model/ — the canonical Data Dictionary v3.0 and DB Schema (a prose source for these annotations; not duplicated here).