# Workspace Cleanup — Design

**Date**: 2026-03-01
**Scope**: Delete stale docs, create/update READMEs, delete plan docs, clean worktrees

## Problem

92 scattered .md files (test reports, quick-starts, analyses) across crates/services.
137 historical plan docs in docs/plans/. 13 crates/services missing README.md.
12 crates missing lib.rs doc comments. 3 tracked .serena tool artifacts. 4 stale worktrees (~13GB).

## Phase 1: Delete Stale Docs

### Scattered .md files to delete (92 total)

**crates/data/** (1):
- tests/EDGE_CASE_FINDINGS.md

**crates/database/** (1):
- QUICK_START.md

**crates/ml/** (18):
- PERFORMANCE_TRACKING.md, MAMBA2_CONFIGURATION_FIX.md, PERFORMANCE_QUICK_START.md
- MAMBA2_DIMENSION_ANALYSIS.md, QUICKSTART_GPU_BENCHMARK.md
- docs/codebase-cleanup/DQN_PARAMETER_CONSISTENCY_AUDIT.md
- docs/dqn_hyperopt_parameter_audit.md, docs/GPU_BENCHMARK_GUIDE.md
- docs/dqn_hyperparameters_analysis.md, docs/QAT_GRADIENT_CHECKPOINTING_WORKAROUND.md
- docs/QAT_GUIDE.md, hyperparams/README.md
- profiling_reports/TFT_INT8_MEMORY_PROFILING_GUIDE.md, profiling_reports/MEMORY_COMPARISON_CHART.md
- src/benchmark/TFT_BENCHMARK_README.md, src/checkpoint/README.md
- tests/TFT_TEST_REPORT.md, tests/MAMBA_TEST_COVERAGE.md
- trained_models/production/tft_real_data/TRAINING_REPORT.md

**crates/risk/** (1):
- docs/TEST_COVERAGE_REPORT.md

**crates/storage/** (1):
- tests/S3_TEST_COVERAGE.md

**crates/trading_engine/** (2):
- docs/audit_trail_persistence_usage.md, docs/TEST_COVERAGE_REPORT.md

**crates/trading_engine/src/types/.serena/** (3 tracked files):
- memories/types_crate_fix_progress.md (+ parent dir)

**services/api_gateway/** (8):
- tests/INTEGRATION_TEST_REPORT.md, tests/RATE_LIMITER_TEST_REPORT.md
- src/metrics/README.md, tests/README.md, benches/README.md
- METRICS_DEPLOYMENT.md, METRICS_ARCHITECTURE.md, REVOCATION_CACHE_USAGE.md
- BENCHMARKS.md, ML_TRAINING_PROXY_INTEGRATION.md, RATE_LIMITER_IMPLEMENTATION.md

**services/backtesting_service/** (7):
- tests/SERVICE_TESTS_REPORT.md, tests/COVERAGE_MAPPING.md
- tests/fixtures/README.md, tests/fixtures/PERFORMANCE.md
- tests/fixtures/QUICKSTART.md, tests/fixtures/ARCHITECTURE.md
- docs/DBN_LOADING_PERFORMANCE_REPORT.md
- DBN_REPOSITORY_USAGE.md, ADVANCED_QUERIES_QUICKREF.md

**services/broker_gateway_service/** (5):
- DEPLOYMENT.md, MONITORING_IMPLEMENTATION.md, METRICS_QUICK_REF.md
- docs/API.md, docs/TROUBLESHOOTING.md, docs/DEPLOYMENT.md

**services/ml_training_service/** (2):
- HYPERPARAMETER_TUNING.md, TRIAL_EXECUTOR_USAGE.md

**services/trading_service/** (2):
- src/streaming/README.md, docs/ml_integration_design.md
- tests/common/README.md

**services/trading_agent_service/** (1):
- README_TLS.md

**bin/fxt/** (7):
- CONFIG_FILE_SUPPORT.md, TUNE_COMMAND_README.md
- docs/AUTHENTICATION.md, docs/ML_TRADING_COMMANDS.md, docs/USAGE.md
- tests/INTEGRATION_TEST_GUIDE.md, tests/TEST_EXECUTION_README.md

**testing/** (13):
- api-gateway-load/CHEAT_SHEET.md, api-gateway-load/QUICK_START.md
- e2e/E2E_TEST_GUIDE.md
- integration/e2e_helpers/INFRASTRUCTURE_VALIDATION.md
- integration/e2e_helpers/USAGE_EXAMPLES.md
- integration/e2e_helpers/QUICKSTART.md
- integration/e2e_helpers/VALIDATION_REPORT.md
- integration/e2e_helpers/QUICK_START_INFRASTRUCTURE.md
- integration/fixtures/README.md
- service-integration/README_DBN_INTEGRATION.md

### Plan docs (137)

Keep `docs/plans/` as historical reference. No action needed.

### Worktrees (4)

- `.claude/worktrees/real-metrics-overhaul` (1KB, abandoned) — delete
- `.claude/worktrees/autonomous-agents` (2.4GB) — delete
- `.claude/worktrees/numeric-type-unification` (4.2GB) — delete
- `.claude/worktrees/training-deploy` (6.5GB) — delete

### Empty directories after deletion

Remove empty `docs/`, `profiling_reports/`, `.serena/` directories left behind.

## Phase 2: READMEs + Doc Comments

### Missing crate READMEs (8):
config, ctrader-openapi, market-data, ml-data, model_loader, risk-data, trading-data, training_uploader

### Missing service READMEs (4):
api_gateway, data_acquisition_service, trading_agent_service, tests

### Missing bin README (1):
bin/fxt

### Update existing READMEs (22):
All existing READMEs get refreshed with standard template.

### Standard template:
```markdown
# <name>
<one-line purpose>

## Key Types / API
<bullet list of primary public types or endpoints>

## Usage
<how to use this crate/service>

## Configuration
<env vars, feature flags if applicable>
```

### lib.rs doc comments (12 crates):
Add `//! <crate-name> — <purpose>` to top of lib.rs for crates missing them.

## Phase 3: Verify

- `SQLX_OFFLINE=true cargo check --workspace`
- `SQLX_OFFLINE=true cargo clippy --workspace --lib -- -D warnings`
- Confirm no broken doc links

## Risk

Low. Only deleting .md files and creating new ones. No Rust code changes except
`//!` doc comments (which can't break compilation).