docs: reorganize docs/ + accuracy audit + drop Node 20 (rebased onto current release tip) - #5262
Merged
Merged
Conversation
Contributor
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
diegosouzapw
force-pushed
the
docs/audit-reorg-v3840
branch
from
June 28, 2026 23:50
6274d08 to
c5a33a1
Compare
…ocs tree cleanup
- Move docs/superpowers/{plans,specs} and docs/research/* into the gitignored,
separately-versioned _tasks/ repo; untrack the two tracked research design docs.
- Add CLAUDE.md "Planning & Research Artifacts" section overriding the superpowers
default save paths (docs/... -> _tasks/...); align REPOSITORY_MAP and
DOCUMENTATION_OVERHAUL_PLAN with the new convention.
- Drop 4 now-obsolete /api/discovery/* entries from check-docs-symbols allowlist
(stale-enforcement) and refresh code/spec path comments to _tasks/...
- Sweeps in concurrent docs-tree restructuring (root-level provider/guide docs,
compression spec cleanup, .mcp.json.example removal).
Phase A — reorganization: - Move 7 orphan root docs into subfolders (providers/ created; TIERS+USAGE_QUOTA→guides/; plugins+PLUGIN_SDK→frameworks/); delete 8 obsolete/redundant docs (SUBMIT_PR superseded by CONTRIBUTING; DOCUMENTATION_OVERHAUL_PLAN; INCIDENT_RESPONSE/PERF_BUDGETS/THREAT_MODEL; 3 ops snapshots). Rebuild README index (was missing ~40 files) + per-folder meta.json nav. - Clean 14 dangling doc-path references in bin/ ops scripts, scripts/, workflow, tests; fix the dockerignore-docs-coverage required-docs path (PROVIDERS→providers/CLAUDE_WEB). Phase B — content accuracy (verified against code, not the audit summary): - Functional: ENVIRONMENT flag defaults (INPUT_SANITIZER/MCP_ENFORCE_SCOPES=true, COMPRESS_DESCRIPTIONS=false, dynamic heap); MCP-SERVER notion tool names (omniroute_*→ notion_*) + counts 87→94; coverage gate 75/70→60/60/60/60 (RELEASE_CHECKLIST, COVERAGE_PLAN, ERROR_SANITIZATION, CONTRIBUTING); pre-push hook description; regenerate PROVIDER_REFERENCE (237). - Count drift: providers 237, executors 70, migrations 106, db modules 94, oauth 19, strategies 17, MCP 94, flags 38, TS 6.0, open-sse ~900/services 294 across architecture/ frameworks/ops docs; AUTO-COMBO 9→12 factors w/ correct DEFAULT_WEIGHTS; REASONING +2 patterns; STEALTH UA defaults; AGENT_PROTOCOLS +cursor-cloud/list-capabilities; LANGUAGE_PACKS +id pack. - Kept Node 20 (runtime guard accepts 20.20.2+; only engines is stricter) and MCP scopes=13 (mcpScopes.ts) — both were correct in the docs; corrected only the attribution.
…metadata sweep - Compression: document the additional built-in engines (CCR, headroom, ionizer, session-dedup) in COMPRESSION_ENGINES; clarify LLMLingua-2 is the ultra-mode SLM backend + cross-ref the extra engines in EXTENDING_COMPRESSION; add the id (Indonesian) language pack to LANGUAGE_PACKS. - AUTO-COMBO: replace the orphan 'How tiers fit' weight table (stale weights) with a pointer to the canonical 12-factor DEFAULT_WEIGHTS table. - Security: merge CLI_TOKEN_AUTH.md (legacy 32-char SHA-256 format) into CLI_TOKEN.md as a 'Legacy format — still accepted' section (server accepts both HMAC + legacy), delete CLI_TOKEN_AUTH.md, drop it from the index + security nav. - Metadata: bump stale frontmatter (version/lastUpdated) to 3.8.40/2026-06-28 across the doc set audited this pass, and normalize the in-body 'Last updated' header lines to match.
…rams/counts - Node minimum is now 22 (aligned with package.json engines). SUPPORTED_NODE_RANGE in src/shared/utils/nodeRuntimeSupport.ts (and the bin/ mirror) drops the 20.x line → '>=22.22.2 <23 || >=24.0.0 <27'; getNodeRuntimeSupport now rejects Node 20 as unsupported-major. Test updated (TDD): node-runtime-support.test.ts asserts Node 20 rejected. Docs aligned (TROUBLESHOOTING ×2, TERMUX, RELEASE_CHECKLIST, CODEBASE, CLI-TOOLS, README, llm.txt + 42 i18n llm.txt mirrors, skills/cli-serve). - Diagrams regenerated: mcp-tools-87 -> mcp-tools-94 (34 base + pool 6 = 94) and auto-combo-9factor -> auto-combo-12factor (correct DEFAULT_WEIGHTS); SVGs re-rendered via mermaid-cli; doc refs + diagrams/README updated; fixed a pre-existing broken resilience-3layers image path. - CLAUDE.md + AGENTS.md aligned to real counts (237 providers, 94 MCP tools / 34 base, 106 migrations, 94 db modules, 12-factor auto-combo, 17 strategies); README provider count 231 -> 237; executor count corrected to 68 (provider executors, excl base/index) and OAuth to 18 across architecture docs. check:docs-all now passes (0 strict drift, 0 broken links); removed dead .mcp.json.example doc link.
The release tip advanced while this work was in flight (Gemini CLI provider/executor removed by #5246, plus other PRs). Re-counted against the current code and updated: providers 237->236, executors 68->67, OAuth modules 18->17, open-sse services 294->298; regenerated PROVIDER_REFERENCE.md (236). check:docs-all passes (0 strict drift).
- CHANGELOG: add [3.8.40] entries for the Node 20.x removal (runtime) and the docs reorganization/accuracy audit. - i18n: nodeIncompatibleHint across all 42 locales no longer lists Node 20.x as supported (ASCII + CJK full-width variants), aligned with the dropped Node 20.
- test: cli-plugin-system asserted docs/dev/plugins.md exists; the file moved to docs/frameworks/PLUGINS.md — point the test at the new path (Unit fast-path 2/2 fix). - frontmatter: PLUGINS.md and PLUGIN_SDK.md moved into the fumadocs-indexed docs/frameworks/ which requires a 'title' frontmatter; the missing frontmatter failed the Next.js MDX build (dast-smoke 'invalid frontmatter'). Added frontmatter to both, plus the providers/ docs (consistency; that folder is not indexed).
diegosouzapw
force-pushed
the
docs/audit-reorg-v3840
branch
from
June 29, 2026 01:06
c5a33a1 to
4769e44
Compare
Merged
tkgo11
pushed a commit
to tkgo11/OmniRoute
that referenced
this pull request
Sep 23, 2026
…current release tip) (diegosouzapw#5262) * docs: move superpowers/research artifacts to isolated _tasks repo + docs tree cleanup - Move docs/superpowers/{plans,specs} and docs/research/* into the gitignored, separately-versioned _tasks/ repo; untrack the two tracked research design docs. - Add CLAUDE.md "Planning & Research Artifacts" section overriding the superpowers default save paths (docs/... -> _tasks/...); align REPOSITORY_MAP and DOCUMENTATION_OVERHAUL_PLAN with the new convention. - Drop 4 now-obsolete /api/discovery/* entries from check-docs-symbols allowlist (stale-enforcement) and refresh code/spec path comments to _tasks/... - Sweeps in concurrent docs-tree restructuring (root-level provider/guide docs, compression spec cleanup, .mcp.json.example removal). * docs: reorganize docs/ tree + fix stale facts across ~26 docs Phase A — reorganization: - Move 7 orphan root docs into subfolders (providers/ created; TIERS+USAGE_QUOTA→guides/; plugins+PLUGIN_SDK→frameworks/); delete 8 obsolete/redundant docs (SUBMIT_PR superseded by CONTRIBUTING; DOCUMENTATION_OVERHAUL_PLAN; INCIDENT_RESPONSE/PERF_BUDGETS/THREAT_MODEL; 3 ops snapshots). Rebuild README index (was missing ~40 files) + per-folder meta.json nav. - Clean 14 dangling doc-path references in bin/ ops scripts, scripts/, workflow, tests; fix the dockerignore-docs-coverage required-docs path (PROVIDERS→providers/CLAUDE_WEB). Phase B — content accuracy (verified against code, not the audit summary): - Functional: ENVIRONMENT flag defaults (INPUT_SANITIZER/MCP_ENFORCE_SCOPES=true, COMPRESS_DESCRIPTIONS=false, dynamic heap); MCP-SERVER notion tool names (omniroute_*→ notion_*) + counts 87→94; coverage gate 75/70→60/60/60/60 (RELEASE_CHECKLIST, COVERAGE_PLAN, ERROR_SANITIZATION, CONTRIBUTING); pre-push hook description; regenerate PROVIDER_REFERENCE (237). - Count drift: providers 237, executors 70, migrations 106, db modules 94, oauth 19, strategies 17, MCP 94, flags 38, TS 6.0, open-sse ~900/services 294 across architecture/ frameworks/ops docs; AUTO-COMBO 9→12 factors w/ correct DEFAULT_WEIGHTS; REASONING +2 patterns; STEALTH UA defaults; AGENT_PROTOCOLS +cursor-cloud/list-capabilities; LANGUAGE_PACKS +id pack. - Kept Node 20 (runtime guard accepts 20.20.2+; only engines is stricter) and MCP scopes=13 (mcpScopes.ts) — both were correct in the docs; corrected only the attribution. * docs: finish content refresh — compression engines, CLI_TOKEN merge, metadata sweep - Compression: document the additional built-in engines (CCR, headroom, ionizer, session-dedup) in COMPRESSION_ENGINES; clarify LLMLingua-2 is the ultra-mode SLM backend + cross-ref the extra engines in EXTENDING_COMPRESSION; add the id (Indonesian) language pack to LANGUAGE_PACKS. - AUTO-COMBO: replace the orphan 'How tiers fit' weight table (stale weights) with a pointer to the canonical 12-factor DEFAULT_WEIGHTS table. - Security: merge CLI_TOKEN_AUTH.md (legacy 32-char SHA-256 format) into CLI_TOKEN.md as a 'Legacy format — still accepted' section (server accepts both HMAC + legacy), delete CLI_TOKEN_AUTH.md, drop it from the index + security nav. - Metadata: bump stale frontmatter (version/lastUpdated) to 3.8.40/2026-06-28 across the doc set audited this pass, and normalize the in-body 'Last updated' header lines to match. * fix(runtime): drop Node 20 from supported range + align all docs/diagrams/counts - Node minimum is now 22 (aligned with package.json engines). SUPPORTED_NODE_RANGE in src/shared/utils/nodeRuntimeSupport.ts (and the bin/ mirror) drops the 20.x line → '>=22.22.2 <23 || >=24.0.0 <27'; getNodeRuntimeSupport now rejects Node 20 as unsupported-major. Test updated (TDD): node-runtime-support.test.ts asserts Node 20 rejected. Docs aligned (TROUBLESHOOTING ×2, TERMUX, RELEASE_CHECKLIST, CODEBASE, CLI-TOOLS, README, llm.txt + 42 i18n llm.txt mirrors, skills/cli-serve). - Diagrams regenerated: mcp-tools-87 -> mcp-tools-94 (34 base + pool 6 = 94) and auto-combo-9factor -> auto-combo-12factor (correct DEFAULT_WEIGHTS); SVGs re-rendered via mermaid-cli; doc refs + diagrams/README updated; fixed a pre-existing broken resilience-3layers image path. - CLAUDE.md + AGENTS.md aligned to real counts (237 providers, 94 MCP tools / 34 base, 106 migrations, 94 db modules, 12-factor auto-combo, 17 strategies); README provider count 231 -> 237; executor count corrected to 68 (provider executors, excl base/index) and OAuth to 18 across architecture docs. check:docs-all now passes (0 strict drift, 0 broken links); removed dead .mcp.json.example doc link. * fix(services): update installer Node hint to >=22.22.2 (aligned with dropped Node 20) * docs: realign counts to current release tip after rebase The release tip advanced while this work was in flight (Gemini CLI provider/executor removed by diegosouzapw#5246, plus other PRs). Re-counted against the current code and updated: providers 237->236, executors 68->67, OAuth modules 18->17, open-sse services 294->298; regenerated PROVIDER_REFERENCE.md (236). check:docs-all passes (0 strict drift). * docs(changelog) + i18n: record Node 20 drop + fix nodeIncompatibleHint - CHANGELOG: add [3.8.40] entries for the Node 20.x removal (runtime) and the docs reorganization/accuracy audit. - i18n: nodeIncompatibleHint across all 42 locales no longer lists Node 20.x as supported (ASCII + CJK full-width variants), aligned with the dropped Node 20. * fix(docs): repair CI breakages from the doc moves - test: cli-plugin-system asserted docs/dev/plugins.md exists; the file moved to docs/frameworks/PLUGINS.md — point the test at the new path (Unit fast-path 2/2 fix). - frontmatter: PLUGINS.md and PLUGIN_SDK.md moved into the fumadocs-indexed docs/frameworks/ which requires a 'title' frontmatter; the missing frontmatter failed the Next.js MDX build (dast-smoke 'invalid frontmatter'). Added frontmatter to both, plus the providers/ docs (consistency; that folder is not indexed).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Full
docs/reorganization + codebase-accuracy audit, plus a runtime change (Node 20.x dropped). Rebased cleanly onto the currentrelease/v3.8.40tip; counts re-verified against the current code (Gemini CLI removal by #5246 → 236 providers / 67 executors / 17 OAuth modules).Reorganization
docs/providers/); 8 obsolete/redundant docs deleted;CLI_TOKEN_AUTHmerged intoCLI_TOKEN.README.mdindex rebuilt (was missing ~40 files) + per-foldermeta.jsonnav updated.bin//scripts//tests cleaned; broken-image link fixed.Content accuracy (verified against code, not the audit summary)
ENVIRONMENTflag defaults (INPUT_SANITIZER/MCP_ENFORCE_SCOPES=true,COMPRESS_DESCRIPTIONS=false, dynamic heap);MCP-SERVERNotion tool names + tool counts (→ 94); coverage gate 75/70 → 60/60/60/60; pre-push hook description; regeneratedPROVIDER_REFERENCE(236).DEFAULT_WEIGHTS; REASONING +2 patterns; STEALTH UA defaults; AGENT_PROTOCOLS +cursor-cloud/list-capabilities; LANGUAGE_PACKS +idpack.mcp-tools-94,auto-combo-12factor).Runtime
SUPPORTED_NODE_RANGE(src/shared/utils/nodeRuntimeSupport.ts+bin/mirror) →>=22.22.2 <23 || >=24.0.0 <27, matchingpackage.jsonengines. Runtime guard now rejects Node 20 (TDD:node-runtime-support.test.ts). Docs/llm.txt/i18nnodeIncompatibleHint/installer hint aligned.CLAUDE.md / AGENTS.md
CHANGELOG
[3.8.40]entries for the Node 20 removal + the docs overhaul.Validation
check:docs-allpasses (0 strict drift, 0 broken links, all canonical counts match) ·check:docs-sync/-symbols/-fabricatedgreen ·node-runtime-supporttest green ·check:node-runtimegreen.