Problem
Import and export documentation is split across docs/features/import/ (8 files) and docs/features/export/ (1 file), with overlapping hubs, stale progress logs, and multiple outstanding files from completed initiatives (#7, #38, #58). Contributors must jump between directories and guess which log is still authoritative.
Meanwhile the reference layer has matured: wire-format detail lives in docs/reference/opengd77/ with a generic format + radio profiles split (radios/baofeng-1701.md, room for more). Feature docs still duplicate column tables and mix adapter behaviour with reference material.
Before adding DM32 (#67), qDMR (#37), and more OpenGD77 radio profiles, we need a tidier import/export doc tree and a single "adding a new vendor" guide that collates process notes scattered across import README, export README, format-fidelity.md, AGENTS.md, and code comments.
Intended outcome
Documentation-only refactor (no behaviour changes unless broken links force tiny comment updates).
1. Collate progress / outstanding logs
Current files (import/):
| File |
Initiative |
Status |
genericise-import-progress.md |
#7 |
Complete |
genericise-import-outstanding.md |
#7 |
All items checked |
opengd77-progress.md |
#38 |
Complete (pending merge note — update) |
opengd77-outstanding.md |
#38 |
Active debt (APRS/DTMF) |
active-import-progress.md |
#58 |
Complete |
active-import-outstanding.md |
#58 |
One optional fixture item |
Actions:
- Archive or delete completed progress logs (or fold a one-paragraph "history" into the hub README).
- Single outstanding file:
import-export-outstanding.md — merge remaining open items from all *-outstanding.md files; remove duplicates; drop completed checkboxes.
- Do not carry forward empty "discovered during execution" sections.
2. Combine into docs/features/import-export/
Replace separate import/ and export/ folders with one feature area:
docs/features/import-export/
README.md # unified hub (problem, status, architecture, merge modes, UI)
outstanding.md # single collated debt log
adding-a-new-vendor.md # contributor guide (see below)
opengd77/
README.md # adapter behaviour only — points to docs/reference/opengd77/
progress.md # optional: keep one short execution log if still useful
dm32/ # placeholder README stub for #67 (optional)
- Merge content from
import/README.md + export/README.md into the new hub without losing merge-mode docs, test commands, or wire-format cross-links.
- Delete empty
docs/features/export/ after migration.
3. OpenGD77 vendor subtree
Move adapter-focused docs to docs/features/import-export/opengd77/:
opengd77.md → slim adapter behaviour doc (classification, detectKind, skip/error behaviour, merge interaction) — column tables stay in docs/reference/opengd77/.
- Cross-link prominently:
- Leave room for
opengd77/radios/<radio>.md only if adapter behaviour genuinely differs per radio; default is one adapter + reference radio profiles.
4. adding-a-new-vendor.md (key deliverable)
Read existing docs and code; produce a checklist-style contributor guide covering:
| Section |
Contents (pull from existing sources) |
| When to add |
New vendor format vs new radio profile on existing format (OpenGD77 example) |
| Reference docs |
Create docs/reference/<vendor>/ wire-format pages; ground truth sources; FK rules |
| Code layout |
src/lib/import/<vendor>/, src/lib/export/<vendor>/; register in registry.ts; vendorFormats.ts |
| Data model |
What must extend Codeplug vs vendorExtras; link data-model |
| Tests |
Per format-fidelity.md: parse unit tests, serialise unit tests, roundtrip.test.ts, merge/system tests, synthetic bundles under src/test/<vendor>/ |
| UI |
ImportDropzone / ImportIntoActivePanel classification; Export page format switcher (#81 secondary nav) |
| Lossy fields |
Document header-only / skipped files; update outstanding.md |
| Docs to update |
Hub README, docs/features/README.md, AGENTS.md, docs/build/testing/README.md, component sidecars |
| Cross-format |
Internal model as hub; optional cross-export tests when two vendors ship |
| Manual verify |
Import folder → CRUD touch → export → re-import diff |
Include a worked example outline pointing at OpenGD77 as the reference implementation.
5. Update inbound links
Fix references across the repo after moves:
AGENTS.md, docs/features/README.md, docs/build/testing/*.md
src/lib/import/opengd77/adapter.ts header comment
- Component sidecars (
ImportIntoActivePanel.md, etc.)
- GitHub issue bodies — only if maintainer wants (optional; links may 404 until merged)
Affected
docs/features/import/ → remove after migration
docs/features/export/ → remove after migration
docs/features/import-export/ — new tree
docs/features/README.md — single Import/export row
.cursor/skills/feature-docs/SKILL.md — note combined folder pattern if convention changes (optional small update)
Notes / dependencies
Out of scope
- Writing DM32 or qDMR adapter docs content (stubs/placeholders only).
- Implementing new vendors.
- Moving
docs/reference/ under import-export/ — reference stays vendor-neutral and shared.
Manual verify
- No broken relative links from
docs/features/import-export/README.md.
adding-a-new-vendor.md links to format-fidelity, data-model, OpenGD77 reference, and registry code paths.
outstanding.md contains only open debt (APRS/DTMF, optional real fixtures, export profile picker follow-ups).
docs/features/README.md index updated.
Workflow note
Branch from origin/main, atomic conventional commits (outstanding collate → new tree + moves → adding-a-new-vendor → link sweep → delete old dirs), PR linking Closes #.
Problem
Import and export documentation is split across
docs/features/import/(8 files) anddocs/features/export/(1 file), with overlapping hubs, stale progress logs, and multiple outstanding files from completed initiatives (#7, #38, #58). Contributors must jump between directories and guess which log is still authoritative.Meanwhile the reference layer has matured: wire-format detail lives in
docs/reference/opengd77/with a generic format + radio profiles split (radios/baofeng-1701.md, room for more). Feature docs still duplicate column tables and mix adapter behaviour with reference material.Before adding DM32 (#67), qDMR (#37), and more OpenGD77 radio profiles, we need a tidier import/export doc tree and a single "adding a new vendor" guide that collates process notes scattered across import README, export README, format-fidelity.md, AGENTS.md, and code comments.
Intended outcome
Documentation-only refactor (no behaviour changes unless broken links force tiny comment updates).
1. Collate progress / outstanding logs
Current files (import/):
genericise-import-progress.mdgenericise-import-outstanding.mdopengd77-progress.mdopengd77-outstanding.mdactive-import-progress.mdactive-import-outstanding.mdActions:
import-export-outstanding.md— merge remaining open items from all*-outstanding.mdfiles; remove duplicates; drop completed checkboxes.2. Combine into
docs/features/import-export/Replace separate
import/andexport/folders with one feature area:import/README.md+export/README.mdinto the new hub without losing merge-mode docs, test commands, or wire-format cross-links.docs/features/export/after migration.3. OpenGD77 vendor subtree
Move adapter-focused docs to
docs/features/import-export/opengd77/:opengd77.md→ slim adapter behaviour doc (classification,detectKind, skip/error behaviour, merge interaction) — column tables stay indocs/reference/opengd77/.docs/reference/opengd77/*.mddocs/reference/opengd77/radios/(MVP: Baofeng 1701)opengd77/radios/<radio>.mdonly if adapter behaviour genuinely differs per radio; default is one adapter + reference radio profiles.4.
adding-a-new-vendor.md(key deliverable)Read existing docs and code; produce a checklist-style contributor guide covering:
docs/reference/<vendor>/wire-format pages; ground truth sources; FK rulessrc/lib/import/<vendor>/,src/lib/export/<vendor>/; register inregistry.ts;vendorFormats.tsCodeplugvsvendorExtras; link data-modelroundtrip.test.ts, merge/system tests, synthetic bundles undersrc/test/<vendor>/ImportDropzone/ImportIntoActivePanelclassification; Export page format switcher (#81 secondary nav)outstanding.mddocs/features/README.md,AGENTS.md,docs/build/testing/README.md, component sidecarsInclude a worked example outline pointing at OpenGD77 as the reference implementation.
5. Update inbound links
Fix references across the repo after moves:
AGENTS.md,docs/features/README.md,docs/build/testing/*.mdsrc/lib/import/opengd77/adapter.tsheader commentImportIntoActivePanel.md, etc.)Affected
docs/features/import/→ remove after migrationdocs/features/export/→ remove after migrationdocs/features/import-export/— new treedocs/features/README.md— single Import/export row.cursor/skills/feature-docs/SKILL.md— note combined folder pattern if convention changes (optional small update)Notes / dependencies
docs/reference/opengd77/— that tree is already correct.Out of scope
docs/reference/underimport-export/— reference stays vendor-neutral and shared.Manual verify
docs/features/import-export/README.md.adding-a-new-vendor.mdlinks to format-fidelity, data-model, OpenGD77 reference, and registry code paths.outstanding.mdcontains only open debt (APRS/DTMF, optional real fixtures, export profile picker follow-ups).docs/features/README.mdindex updated.Workflow note
Branch from
origin/main, atomic conventional commits (outstanding collate → new tree + moves → adding-a-new-vendor → link sweep → delete old dirs), PR linkingCloses #.