docs: authoritative OpenGD77 CPS CSV field reference under docs/reference/opengd77/

[pskillen]

Problem

OpenGD77 CPS CSV is our first (but not only) vendor interchange format (#38), but the field mapping documentation is scattered and incomplete:

• docs/features/import/opengd77.md lists column → model mappings for import, with a short export pointer.
• docs/features/export/README.md defers column detail back to the import doc.

Neither is an authoritative reference for third-party ↔ internal field mapping. Missing today:

• Bidirectional conversion rules (e.g. Yes/No booleans, Off/On VOX, ID Type → TalkGroup vs Contact, name-based FK denormalisation on export).
• Validation constraints — required columns, allowed enum values, parse failure vs skip behaviour.
• Field size / cardinality limits — channel name length, zone member cap (80), TG list member cap (32), etc.
• Lossy vs lossless fields — what round-trips via vendorExtras, what is header-only (DTMF.csv, APRS.csv), what is not modelled.
• Planned adapter behaviour that needs a stable doc home — e.g. multi-talkgroup channel denormalisation (#36), future qDMR YAML (#37).

Feature docs under docs/features/import/ and docs/features/export/ should describe how the feature works in the app (UI, registry, progress logs). Canonical vendor format knowledge should live alongside other reference material (cf. docs/reference/bands.md), with implementation code (src/lib/import/opengd77/, src/lib/export/opengd77/) expected to mirror it.

Intended outcome

Create docs/reference/opengd77/ as the authoritative OpenGD77 CPS CSV reference and refactor existing feature docs to link there instead of duplicating column tables.

Proposed reference layout

File	Contents
docs/reference/opengd77/README.md	Hub — file set overview, classification heuristics, skip vs error, links to per-file docs
docs/reference/opengd77/file-format.md	Cross-cutting rules: header-name parsing (not index), case-sensitive name FKs, round-trip guarantees, vendorExtras policy
docs/reference/opengd77/channels.md	Channels.csv — every column, internal field, import parse, export serialise, conversion fns, validation
docs/reference/opengd77/zones.md	Zones.csv — Channel1…Channel80, zone cap, nested-zone export notes (#33 if relevant)
docs/reference/opengd77/contacts.md	Contacts.csv — Group/Private, TS Override
docs/reference/opengd77/tg-lists.md	TG_Lists.csv — Contact1…Contact32, promiscuous RX semantics
docs/reference/opengd77/dtmf-aprs.md	DTMF.csv / APRS.csv — header-only status, future modelling notes
docs/reference/opengd77/limits.md	CPS-imposed max lengths, member counts, naming constraints (source: OpenGD77 CPS / firmware where known)
docs/reference/opengd77/multi-talkgroup.md	Placeholder/stub for #36 denormalisation rules (channel × TG expansion, naming template, zone membership)

Adjust filenames if a simpler split works — goal is one obvious place per concern, not feature-doc sprawl.

Per-field table shape (each file)

For every vendor column, document at minimum:

Vendor header	Internal field	Required	Max size / range	Import rule	Export rule	Round-trip	Notes

Populate from existing code:

• Headers: src/lib/import/opengd77/columns.ts
• Import parsers: src/lib/import/opengd77/parse.ts
• Export serialisers: src/lib/export/opengd77/serialise.ts
• Internal shapes: src/models/codeplug.ts + data-model docs

Feature doc updates

• Slim import/opengd77.md to adapter-specific behaviour (classification, code anchors, progress links) — link to reference for column detail.
• Slim export/README.md OpenGD77 section similarly.
• Add docs/reference/opengd77/ row to docs/features/README.md Reference table.
• Cross-link from data-model where vendor interchange is relevant.

Affected

• docs/reference/opengd77/ (new)
• docs/features/import/opengd77.md
• docs/features/export/README.md
• docs/features/README.md
• Optionally: brief comment in columns.ts / adapter files pointing at the reference (mirror pattern in src/lib/bands.ts → docs/reference/bands.md).

Notes / dependencies

• Builds on shipped import/export (#38) — document what exists today; flag gaps where code and docs disagree (code wins until fixed).
• Feeds #36 — multi-TG denormalisation rules should be drafted in reference before/alongside implementation.
• Feeds #37 — establishes the docs/reference/<vendor>/ pattern for future formats (e.g. docs/reference/qdmr/ later).
• Research CPS limits from OpenGD77 CPS UI / firmware docs or qDMR's OpenGD77Codeplug where our code is silent.
• Use gitignored sample-exports/ for examples; do not commit operator codeplugs.

Out of scope

• Implementing new validation or export behaviour — this ticket is documentation only (file follow-up issues for code gaps discovered during the audit).
• qDMR YAML reference docs (#37) — separate directory when that adapter is scoped.
• Native YAML schema (#10) — internal format, not vendor reference.

Workflow note (for whoever picks this up)

Docs-only work: branch from origin/main, use atomic conventional commits per logical unit (e.g. docs(reference): add opengd77 hub, docs(import): link opengd77 adapter to reference), open a PR linking Closes #. No progress/outstanding logs needed unless the audit surfaces code bugs worth ticketing.

[pskillen]

Reference docs shipped in branch 43/pskillen/opengd77-reference:

• Generic: docs/reference/opengd77/ — hub, file-format, channels, zones, contacts, tg-lists, dtmf-aprs, multi-talkgroup stub
• Radio profile: docs/reference/opengd77/radios/baofeng-1701.md — limits, feature availability, layout conventions

Follow-up issues from audit:

• feat(export): OpenGD77 radio profile selection at export time #72 — export radio profile picker
• feat(meta): CodeplugMeta.radioProfile for import provenance #73 — CodeplugMeta.radioProfile
• fix(opengd77): wire normalisation and import warnings per reference audit #74 — wire normalisation / import warnings