chore: consolidate documentation — delete status/fix/progress cruft #2

2026-04-18T18:56:56Z

nsatoshi commented

2026-04-18 18:56:56 +00:00

Summary

PR #2 of the 11-PR completion sequence. Pure documentation consolidation — no code changes.

Before: 335 tracked .md files; 14 README-like docs at the top level; docs/ contained ~234 files, most of them auto/LLM-generated status reports (ALL_*_COMPLETE_*, *_FIX.md, DEPLOYMENT_*_FINAL.md, etc.).

After: 132 tracked .md files. Exactly five top-level docs: README.md, QUICKSTART.md, RUNBOOK.md, CONTRIBUTING.md, CHANGELOG.md (moved up from docs/). 205 files changed, +8 / -37 633 lines.

What was kept in `docs/`

API: API_DOCUMENTATION.md, EXPLORER_API_ACCESS.md, EXPLORER_API_REFERENCE.md, docs/api/, docs/openapi/.
CCIP operational & security references (ops runbook, security best practices, security incident response, access control, rate limits, best practices, receiver requirements, token-pool architecture, router configuration, router native-ETH check, verification checklist, monitor metrics, fee structure, fee-and-limitation analysis).
Chainlist references.
Architecture: BRIDGE_CONTRACT_ARCHITECTURE.md, COMPLIANCE_ARCHITECTURE_EXPLANATION.md, TIERED_ARCHITECTURE_*, REUSABLE_COMPONENTS_EXTRACTION_PLAN.md.
Deployment guides (not status): DEPLOYMENT.md, DEPLOYMENT_GUIDE.md, DEPLOYMENT_METHOD_REMIX_IDE.md, DEPLOYMENT_METHOD_VALIDATOR.md.
Reference: DATABASE_CONNECTION_GUIDE.md, INTEGRATION_GUIDES.md, METAMASK_AND_PROVIDER_INTEGRATION.md, PRODUCTION_CHECKLIST.md, PR_WORKFLOW_RECOMMENDATION.md, PULL_REQUEST_GUIDE.md, TOKEN_MECHANISM_DOCUMENTATION.md, WRAP_AND_BRIDGE_TO_ETHEREUM.md.
Legal compliance: LEGAL_COMPLIANCE_*.
All of docs/specs/** (architecture specs).

What was deleted

Pattern-matched, not file-by-file, using /tmp/curate_docs.py:

All ALL_*_COMPLETE*, *_FIX.md, *_FIXED*, *_FINAL*, *_COMPLETE*, *_COMPLETION*, *_STATUS*, *_PROGRESS*, *_SUMMARY* in docs/.
All BLOCKSCOUT_* fix/status/crash/initialization/schema/yaml/skip/next-steps/start-and-build/database-credentials docs (the last contained passwords).
CCIP_IMPLEMENTATION_*, CCIP_CURRENT_STATUS, CCIP_GAP_*, CCIP_COMPLETE_TASK_CATALOG, CCIP_SETUP_COMPLETION_STATUS (gap analyses and setup status reports are not a sustained reference).
NPMPLUS_CREDENTIALS_GUIDE.md (contained creds).
LETSENCRYPT_CONFIGURATION_GUIDE.md (contained creds; will be re-introduced as runbook content post secret-scrub).
docs/diagnostic-reports/, docs/feature-flags/ (run-time artifacts).
Top-level: START_HERE.md, ALL_NEXT_STEPS_COMPLETE_FINAL.md, IP_CONFLICT_INVESTIGATION.md, NET1_REMOVED_ISSUE.md, NPMPLUS_UPDATE_GUIDE.md, README_BRIDGE.md, README_DEPLOYMENT.md, chain_id_138_explorer_virtual_banking_vtm_platform_plan.md.

README.md link fix

Dead links (START_HERE, README_DEPLOYMENT, COMPLETE_DEPLOYMENT, DEPLOYMENT_COMPLETE_FINAL) in README.md were replaced with links to the five canonical top-level docs + the docs/ index. A full README rewrite is scheduled for PR #11.

Why

The previous doc tree made it impossible to tell which file was current. A single BLOCKSCOUT_* troubleshooting thread had 12 overlapping markdowns (BLOCKSCOUT_FIX_CORRECTED, BLOCKSCOUT_FIX_FINAL, BLOCKSCOUT_FIX_WORKING, etc.). Deleting obsolete reports and keeping reference material makes the repo navigable and surfaces the real open questions.

Verification

No code / config / migration files touched — git diff --stat shows only .md deletions plus the README.md link edit and the docs/CHANGELOG.md → CHANGELOG.md rename.
rg 'START_HERE|README_DEPLOYMENT|COMPLETE_DEPLOYMENT|NPMPLUS_CREDENTIALS' returns no hits in the remaining .md set.
find . -name 'ALL_*.md' returns nothing.

Completion criterion advanced

1. Clean repo hygiene — "All ALL_*_COMPLETE*.md, BLOCKSCOUT_*_FIX*.md, DEPLOYMENT_*_FINAL*.md etc. deleted …"

Still outstanding: running gitleaks over history (PR #5 wiring), rewriting the top-level README.md / new ARCHITECTURE.md / API.md (PR #11).

## Summary PR #2 of the 11-PR completion sequence. Pure documentation consolidation — no code changes. **Before:** 335 tracked `.md` files; 14 README-like docs at the top level; `docs/` contained ~234 files, most of them auto/LLM-generated status reports (`ALL_*_COMPLETE_*`, `*_FIX.md`, `DEPLOYMENT_*_FINAL.md`, etc.). **After:** 132 tracked `.md` files. Exactly five top-level docs: `README.md`, `QUICKSTART.md`, `RUNBOOK.md`, `CONTRIBUTING.md`, `CHANGELOG.md` (moved up from `docs/`). 205 files changed, +8 / -37 633 lines. ## What was kept in `docs/` - API: `API_DOCUMENTATION.md`, `EXPLORER_API_ACCESS.md`, `EXPLORER_API_REFERENCE.md`, `docs/api/`, `docs/openapi/`. - CCIP operational & security references (ops runbook, security best practices, security incident response, access control, rate limits, best practices, receiver requirements, token-pool architecture, router configuration, router native-ETH check, verification checklist, monitor metrics, fee structure, fee-and-limitation analysis). - Chainlist references. - Architecture: `BRIDGE_CONTRACT_ARCHITECTURE.md`, `COMPLIANCE_ARCHITECTURE_EXPLANATION.md`, `TIERED_ARCHITECTURE_*`, `REUSABLE_COMPONENTS_EXTRACTION_PLAN.md`. - Deployment guides (not status): `DEPLOYMENT.md`, `DEPLOYMENT_GUIDE.md`, `DEPLOYMENT_METHOD_REMIX_IDE.md`, `DEPLOYMENT_METHOD_VALIDATOR.md`. - Reference: `DATABASE_CONNECTION_GUIDE.md`, `INTEGRATION_GUIDES.md`, `METAMASK_AND_PROVIDER_INTEGRATION.md`, `PRODUCTION_CHECKLIST.md`, `PR_WORKFLOW_RECOMMENDATION.md`, `PULL_REQUEST_GUIDE.md`, `TOKEN_MECHANISM_DOCUMENTATION.md`, `WRAP_AND_BRIDGE_TO_ETHEREUM.md`. - Legal compliance: `LEGAL_COMPLIANCE_*`. - All of `docs/specs/**` (architecture specs). ## What was deleted Pattern-matched, not file-by-file, using `/tmp/curate_docs.py`: - All `ALL_*_COMPLETE*`, `*_FIX.md`, `*_FIXED*`, `*_FINAL*`, `*_COMPLETE*`, `*_COMPLETION*`, `*_STATUS*`, `*_PROGRESS*`, `*_SUMMARY*` in `docs/`. - All `BLOCKSCOUT_*` fix/status/crash/initialization/schema/yaml/skip/next-steps/start-and-build/database-credentials docs (the last contained passwords). - `CCIP_IMPLEMENTATION_*`, `CCIP_CURRENT_STATUS`, `CCIP_GAP_*`, `CCIP_COMPLETE_TASK_CATALOG`, `CCIP_SETUP_COMPLETION_STATUS` (gap analyses and setup status reports are not a sustained reference). - `NPMPLUS_CREDENTIALS_GUIDE.md` (contained creds). - `LETSENCRYPT_CONFIGURATION_GUIDE.md` (contained creds; will be re-introduced as runbook content post secret-scrub). - `docs/diagnostic-reports/`, `docs/feature-flags/` (run-time artifacts). - Top-level: `START_HERE.md`, `ALL_NEXT_STEPS_COMPLETE_FINAL.md`, `IP_CONFLICT_INVESTIGATION.md`, `NET1_REMOVED_ISSUE.md`, `NPMPLUS_UPDATE_GUIDE.md`, `README_BRIDGE.md`, `README_DEPLOYMENT.md`, `chain_id_138_explorer_virtual_banking_vtm_platform_plan.md`. ## README.md link fix Dead links (`START_HERE`, `README_DEPLOYMENT`, `COMPLETE_DEPLOYMENT`, `DEPLOYMENT_COMPLETE_FINAL`) in `README.md` were replaced with links to the five canonical top-level docs + the `docs/` index. A full README rewrite is scheduled for PR #11. ## Why The previous doc tree made it impossible to tell which file was current. A single `BLOCKSCOUT_*` troubleshooting thread had 12 overlapping markdowns (`BLOCKSCOUT_FIX_CORRECTED`, `BLOCKSCOUT_FIX_FINAL`, `BLOCKSCOUT_FIX_WORKING`, etc.). Deleting obsolete reports and keeping reference material makes the repo navigable and surfaces the real open questions. ## Verification - No code / config / migration files touched — `git diff --stat` shows only `.md` deletions plus the `README.md` link edit and the `docs/CHANGELOG.md → CHANGELOG.md` rename. - `rg 'START_HERE|README_DEPLOYMENT|COMPLETE_DEPLOYMENT|NPMPLUS_CREDENTIALS'` returns no hits in the remaining `.md` set. - `find . -name 'ALL_*.md'` returns nothing. ## Completion criterion advanced > **1. Clean repo hygiene** — "All `ALL_*_COMPLETE*.md`, `BLOCKSCOUT_*_FIX*.md`, `DEPLOYMENT_*_FINAL*.md` etc. deleted …" Still outstanding: running `gitleaks` over history (PR #5 wiring), rewriting the top-level `README.md` / new `ARCHITECTURE.md` / `API.md` (PR #11).

nsatoshi referenced this issue from a commit

2026-04-18 19:02:35 +00:00

fix(security): fail-fast on missing JWT_SECRET, harden CSP, strip hardcoded passwords

nsatoshi referenced this pull request

2026-04-18 19:03:04 +00:00

fix(security): fail-fast on missing JWT_SECRET, harden CSP, strip hardcoded passwords #3

nsatoshi referenced this pull request

2026-04-18 19:31:05 +00:00

docs: rewrite README, add ARCHITECTURE.md (Mermaid), add API.md from swagger.yaml #11

nsatoshi merged commit a6ce14ed20 into master

2026-04-18 19:35:39 +00:00

nsatoshi referenced this issue from a commit