Repo Structure Cleanup — 9-PR Plan

Goal: Bring the AetherSDR repo's top-level structure and docs/ directory up
to a portfolio-quality OSS standard. Root drops from ~25 entries to ~15
(every file has a clear purpose). docs/ drops from 40+ entries to ~18
(every file is genuinely a doc, not data/asset/orchestrator artifact).
AI + Human collaboration narrative becomes prominent in README.

Scope: 9 PRs, all independent of each other except where noted. Most
are mechanical file moves with minimal code reference updates.

Risk posture: Every PR keeps changes small and surgical. CMakeLists.txt
path updates are the only build-system touches; doc cross-references are
sed-replaceable.

Order: PRs are independent — order doesn't matter for correctness, but
the recommended sequence below maximizes early visual impact:

1. Setup scripts out of root (cosmetic win PHONE applet: DEXP commands rejected on firmware v1.4.0.0 #1)
2. README "How AetherSDR Is Built" (portfolio impact)
3. RECENTER / STYLEGUIDE / SECURITY-AUDIT relocation
4. AetherClaude orchestrator docs to correct repo
5. Logo / screenshot reorganization
6. cty.dat + AetherSDR.desktop relocation
7. Icon / .rc / .entitlements → packaging
8. Issue-NNNN planning docs → PR descriptions or archive
9. PR template + SUPPORT + ROADMAP new files

PR 1 — Move setup-.ps1 + setup-.sh from root to scripts/setup/

Files to move

Cross-reference updates

Grep for each filename across the codebase and update paths:

git grep -l "setup-deepfilter\|setup-fftw\|setup-hidapi\|setup-onnxruntime\|setup-opus"

Expected hits:

• CMakeLists.txt (if any setup scripts are invoked from build) — update path
• README.md (likely a "Building on Windows" section that references these)
• CONTRIBUTING.md (build instructions)
• docs/*.md (any "how to set up X" docs)
• GitHub workflows (.github/workflows/windows-installer.yml, possibly others)

Risk

Very low. Pure file move. If CI or local builds break, it's because we
missed a path reference — fixable in seconds.

Test plan

1. git mv the files (preserves history)
2. Update all references found in grep
3. Local build (Linux): cmake -B build && cmake --build build should still succeed
4. Push as PR, watch CI: check-paths, build, check-windows must all pass
5. Spot-check Windows build (manual or via the windows-installer.yml workflow)

Acceptance criteria

• All 6 setup files reside in scripts/setup/
• Zero references to old paths remain (git grep "^setup-" || git grep "/setup-")
• CI green on PR + main
• Root directory file count drops by 6

Estimated effort

30 minutes.

PR 2 — Add "How AetherSDR Is Built" section to README

Goal

Make the AI-augmented development model visible from the first README view.
This is the highest-impact PR for portfolio / hiring-manager skim.

Content to add

Between Highlights and Supported Hardware sections, insert a new
## How AetherSDR Is Built section that calls out:

• Solo maintainer (Jeremy KK7GWY) + Claude Code as primary dev environment
• AetherClaude orchestrator bot for triage + autonomous fixes
• Community contributors using own AI tools (Codex, Copilot, Cursor, Gemini)
• Constitution governing the multi-agent contribution model (link)
• Branch protection enforcing signed commits + CI + CODEOWNERS review
• AGENTS.md as canonical project guide for all AI tools

Suggested wording is in the audit report; tighten as needed for tone.

Cross-reference updates

None. New content only.

Risk

Zero. Pure addition to README.

Test plan

1. Add the new section
2. Render preview locally (e.g., glow README.md or paste into GitHub gist)
3. Verify links to AGENTS.md and CONSTITUTION.md resolve

Acceptance criteria

• New section between Highlights and Supported Hardware
• Links to AGENTS.md and CONSTITUTION.md
• Reads as "this project is taking AI collaboration seriously" within
  the first 200 words of the section
• No other README content modified

Estimated effort

20 minutes including review.

PR 3 — Move RECENTER.md, STYLEGUIDE.md, SECURITY-AUDIT.md to docs/

Files to move (or delete)

Rationale per file

• RECENTER.md is a code-architecture description from
  aether/recenter-policy worktree. Belongs in docs/architecture/ so it's
  alongside architecture-pipelines.md.
• STYLEGUIDE.md is the applet design language doc. Belongs in docs/
  alongside dialog-patterns.md.
• SECURITY-AUDIT.md is currently untracked. Decision needed: either
  commit (with public-audit framing) or .gitignore it as a maintainer
  notebook.

Cross-reference updates

git grep -l "RECENTER.md\|STYLEGUIDE.md\|SECURITY-AUDIT.md"

Update any links in CLAUDE.md, AGENTS.md, CONTRIBUTING.md, other docs.

Create docs/architecture/ subdirectory; consider whether
architecture-pipelines.md also belongs there (deferred to a future
PR — out of scope here).

Risk

Low. File moves + ~5 link updates.

Test plan

1. git mv (preserves history)
2. Update cross-references in docs
3. Spot-check rendered output of moved docs on GitHub web view
4. Verify no broken links via a markdown link checker

Acceptance criteria

• All 3 files relocated (or SECURITY-AUDIT explicitly deleted/gitignored)
• All cross-references updated
• Root markdown file count drops to 11 (the 11 genuine project-health docs)

Estimated effort

30 minutes.

PR 4 — Move AetherClaude-*.md docs from this repo to the aetherclaude repo

Files to relocate

Move from ~/build/AetherSDR/docs/ to ~/build/aetherclaude/docs/:

Rationale

These describe the AetherClaude orchestrator bot's architecture, not
AetherSDR itself. They were written in this repo for convenience but belong
in the AetherClaude repo's docs/. Keeping them here pollutes
AetherSDR's docs index and confuses readers about project scope.

Execution

This is two separate commits across two repos:

1. In ~/build/aetherclaude/:

   • mkdir -p docs/
   • Copy the 4 files in (preserving content)
   • Commit + push as part of an aetherclaude repo PR

2. In ~/build/AetherSDR/:

   • git rm docs/AetherClaude-*-Plan.md and docs/AetherClaude-Security-Architecture.md
   • Commit + ship

Cross-reference updates

git grep -l "AetherClaude-Skills-Plan\|AetherClaude-Cisco-Scanner\|AetherClaude-Security-Architecture\|AetherClaude-eBPF-Demo"

Update any AetherSDR docs that reference these (likely few — they're internal
to AetherClaude).

Risk

Low. Net deletion from this repo; addition to aetherclaude repo. Histories
diverge but content is preserved.

Test plan

1. Verify content lands in aetherclaude repo intact
2. Verify removal from AetherSDR repo doesn't break any link in this repo
3. Update any pointer in ~/.claude/projects/ memory entries or docs
   that reference these by path

Acceptance criteria

• 4 files removed from AetherSDR docs/
• 4 files added to aetherclaude repo (separate PR there)
• Zero references to old paths in AetherSDR repo

Estimated effort

45 minutes (spans two repos).

PR 5 — Move logo + screenshot assets to docs/assets/; archive old screenshots

Files to move

To docs/assets/ (new subdirectory):

To docs/assets/screenshots/archive/:

Cross-reference updates

• README.md references docs/screenshot-v5.png — update to
  docs/assets/screenshot-current.png
• .gitignore references docs/logo-original.jpg and
  docs/logo_upscayl.png (currently set to ignore them but they're
  tracked) — review and update

Rationale

docs/ should be docs (markdown), not assets (images). docs/assets/ is the
standard subdivision. Using a stable filename like screenshot-current.png
means future README updates don't need to bump a version suffix every time.

Risk

Very low. File moves + one README link update.

Test plan

1. git mv (preserves history for non-.gitignore'd files)
2. Update README link
3. GitHub web view of README renders the image
4. Verify rendered output looks correct

Acceptance criteria

• All assets in docs/assets/ (new dir)
• Old screenshots archived
• README still renders correctly
• docs/ directory dropped to ~28 markdown files (still has data files for now)

Estimated effort

30 minutes.

PR 6 — Move cty.dat + AetherSDR.desktop to appropriate dirs

Files to move

Cross-reference updates

git grep -l "cty.dat\|AetherSDR.desktop"

Expected hits:

• CMakeLists.txt (likely installs the .desktop file; bundles cty.dat)
• AppImage workflow (.github/workflows/appimage.yml)
• Linux package scripts in packaging/

Risk

Medium-low. cty.dat may be referenced in C++ source if the application
opens it directly — verify before moving.

Test plan

1. git grep -F 'cty.dat' (case-sensitive, exact path string)
2. Update C++ source paths if any reference the root path
3. Update CMakeLists.txt + AppImage workflow
4. Local build + run + verify country lookups still work
5. AppImage workflow run produces a valid artifact

Acceptance criteria

• cty.dat in resources/
• AetherSDR.desktop in packaging/linux/
• Local build still works
• AppImage workflow produces working AppImage with country prefix lookups
  functional

Estimated effort

45 minutes (involves CMake + runtime verification).

PR 7 — Move Windows/macOS packaging artifacts to packaging/

Files to move

Consolidation

After this PR, macos/ directory is empty and can be removed. The
packaging/ directory structure becomes:

packaging/
├── linux/
│   └── AetherSDR.desktop
├── macos/
│   └── AetherSDR.entitlements
└── windows/
    ├── AetherSDR.ico
    └── AetherSDR.rc

Cross-reference updates

• CMakeLists.txt (Windows: target_sources(... AetherSDR.rc))
• .github/workflows/windows-installer.yml
• .github/workflows/macos-dmg.yml
• Any packaging scripts in packaging/

Risk

Low-medium. Windows .rc file path affects icon embedding; macOS entitlements
path affects signing.

Test plan

1. Move files
2. Update all CMake + workflow references
3. Local CMake regen — no errors
4. Windows installer workflow runs and produces working .exe with icon
5. macOS DMG workflow runs, signing succeeds, notarization succeeds

Acceptance criteria

• All three files relocated
• Windows installer ships with icon present
• macOS DMG signs + notarizes successfully
• macos/ directory removed
• docs/ directory drops by 2 entries

Estimated effort

45 minutes.

PR 8 — Move issue-NNNN-*.md and one-off planning docs to PR descriptions or docs/archive/

Files to relocate

Review each individually; some have value as historical docs, others should
be PR-description-only:

Process per file

For each .md planning doc:

1. git log -1 --format="%H %s" -- docs/issue-NNNN-*.md → identify the
   originating issue/PR
2. Check the issue/PR description on GitHub — does it have the content?
   • Yes: git rm and add a comment to the issue noting the doc is
     now superseded by the issue description itself
   • No: copy the content as a comment on the originating issue, then
     git rm
3. If neither (the doc references something else entirely), move to
   docs/archive/<topic>.md with a # Archived YYYY-MM-DD header

For .csv / .settings / .config data files:

1. Check if any test in tests/ references the file
2. If yes: git mv to tests/fixtures/
3. If no: git mv to docs/data/ (new subdir)

Cross-reference updates

git grep -l "issue-2136\|TX_SYNC_FIX_REPORT\|aether-dsp-session-notes\|audio_test_plan\|profile-import-export-manual-checklist\|SSDR.settings\|SmartSDR.exe.config\|rxapplet_mode_settings\|vfo_mode_filters"

Update each reference.

Risk

Medium. Requires reviewing 10 files for current relevance. Some may turn out
to still be load-bearing for ongoing work.

Test plan

1. Per-file review (above process)
2. Update cross-references
3. Verify any tests still pass if data fixtures moved
4. Commit

Acceptance criteria

• All 10 files either deleted (with content preserved in GitHub
  issue/PR) or relocated to docs/archive/, docs/data/, or
  tests/fixtures/
• docs/ directory contains only:
  • Markdown architecture/user docs (~18 files)
  • assets/ subdirectory
  • Possibly data/ and/or archive/ subdirectories

Estimated effort

2 hours (lots of small judgement calls).

PR 9 — Add .github/PULL_REQUEST_TEMPLATE.md, SUPPORT.md, ROADMAP.md

New files

.github/PULL_REQUEST_TEMPLATE.md

## Summary

<!-- One-paragraph description of what changes and why. -->

## Constitution principle honored

<!-- Cite the principle by Roman numeral if principle-relevant.
     E.g. "Principle V — nested-JSON persistence for the new feature." -->

## Test plan

- [ ] Local build passes (`cmake --build build`)
- [ ] Behavior verified on a real radio if applicable
- [ ] Existing tests pass
- [ ] Manual reproduction steps documented if user-reported bug

## Checklist

- [ ] Signed commits (see `docs/COMMIT-SIGNING.md`)
- [ ] Fix references the issue with `Fixes #NNNN` or `Closes #NNNN`
- [ ] Documentation updated if behavior changed
- [ ] No new flat-key `AppSettings` calls (Principle V)
- [ ] All meter UI uses `MeterSmoother` (Principle II)

SUPPORT.md

# Getting Help with AetherSDR

- **General questions:** GitHub Discussions —
  https://github.com/aethersdr/AetherSDR/discussions
- **Bug reports:** Use the bug-report issue template
  (Help → Support → File an Issue in the app)
- **Feature requests:** Use the feature-request issue template
- **Real-time chat:** [Discord / IRC / etc. — link if any]

For commercial support: contact the project maintainer
(KK7GWY@aethersdr.com).

This is volunteer-maintained open-source software. No SLA, no guaranteed
response time. Bug reports with attached support bundles get priority.

ROADMAP.md

# AetherSDR Roadmap

## Current cycle: post-v26.5.2.1

Items being actively worked or queued for the next release cycle.
See GitHub Issues + Projects for live tracking.

### In flight

- [ ] AetherModem Phase 1 — 1200 baud VHF AX.25 packet TX
- [ ] AppSettings nested-JSON refactor (Principle V migration)
- [ ] Per-band ATU pre-tune integration with SWR sweep
  (#2822 — shared computeContiguousRegions helper)

### Queued

- [ ] RF2K-S amp interop restoration with adaptive TCI identity (#2806)
- [ ] FreeDV Reporter integration polish
- [ ] Additional region band plans (DXCC entities outside IARU R1/2/3)

## Recently shipped (last 30 days)

See [CHANGELOG.md](CHANGELOG.md) for the complete shipping log.

Cross-reference updates

None — net new files.

Risk

Zero. Pure addition.

Test plan

1. Open a draft PR — verify the new template appears in the PR body editor
2. Visit the GitHub repo Settings → Community Standards page — verify
   SUPPORT.md is detected
3. Render ROADMAP.md on GitHub web view

Acceptance criteria

• .github/PULL_REQUEST_TEMPLATE.md exists and auto-populates new PRs
• SUPPORT.md exists and "Get help" sidebar link appears in GitHub UI
• ROADMAP.md exists with current cycle goals

Estimated effort

45 minutes (mostly drafting ROADMAP content with maintainer input).

Execution sequence

PRs 1, 2, 5 are the quickest wins. PR 4 (AetherClaude relocation) spans
two repos and is the most isolated. PR 7 (packaging) is the highest-risk
because Windows/macOS signing flows depend on the paths.

Recommended sequence:

1. PR 1: setup scripts (30 min) — quick win
2. PR 2: README "How AetherSDR Is Built" (20 min) — portfolio impact
3. PR 3: RECENTER / STYLEGUIDE (30 min) — root cleanup
4. PR 5: logo + screenshot relocation (30 min)
5. PR 9: PR template + SUPPORT + ROADMAP (45 min) — net-new
6. PR 6: cty.dat + .desktop (45 min)
7. PR 4: AetherClaude docs cross-repo (45 min)
8. PR 7: Windows .ico/.rc + macOS .entitlements (45 min, highest risk)
9. PR 8: issue-NNNN planning docs (2 hours, most judgement calls)

Total effort: ~7 hours of focused work, distributed across one or
two work sessions.

Coordination

All 9 PRs can be assigned to AetherClaude if desired (most are
mechanical) — except PR 8 (issue archival), which requires per-file
judgement calls best done by the maintainer.

Each PR self-assigns to its agent per the Issue/PR Claim Protocol
(gh pr edit --add-assignee @me).

Per Principle X (Claims Are Atomic And Mortal): each PR must verify
its base is current origin/main before producing the patch. The
recent stale-snapshot incidents (PR #2780) are the canonical case this
exists to prevent — and a 9-PR cleanup is exactly the shape where
that risk re-emerges.