docs: reduce public doc noise and archive internal notes#44
Open
maxkle1nz wants to merge 1 commit into
Open
Conversation
Move historical build/adversary/hardening packets out of the default public docs lane, relabel the ambiguous-but-useful support pages, and repair the benchmark references so the canonical onboarding path stays readable. Constraint: Keep the primary public chain intact: README -> wiki entrypoints -> examples/deployment/integrations. Rejected: Delete old docs outright from the repo | too destructive for material that may still be useful as historical implementation evidence. Rejected: Leave all internal packets in the public docs root | it makes the project feel noisier and less trustworthy for new users. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Archive historical/internal notes instead of deleting them unless inbound-link checks and maintainers explicitly approve full removal. Tested: inbound-link grep before moves; benchmark link repair in docs/wiki/src/benchmarks.md and docs/benchmarks/README.md; manual review of relabel banners Not-tested: external link crawling across the rendered wiki/pages after merge
There was a problem hiding this comment.
Pull request overview
This PR reduces noise in the public documentation surface by archiving historical/internal artifacts under docs/archive/internal-notes/ and clarifying which remaining docs are canonical vs supporting references.
Changes:
- Added “Status” banners to several public-facing docs to clarify intended usage vs canonical onboarding.
- Updated benchmark documentation to point to archived benchmark research materials.
- Added a new
docs/archive/internal-notes/hierarchy containing historical/internal design/build reports and planning notes.
Reviewed changes
Copilot reviewed 7 out of 37 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| USE-CASES.md | Adds a status banner to frame the doc as supporting reference, pointing users to canonical entrypoints. |
| docs/wiki/src/benchmarks.md | Updates benchmark artifact references to the archived internal-notes location. |
| docs/OPENCLAW-NATIVE-FASTPATH.md | Adds a status banner clarifying this is a host-specific architecture note, not default onboarding. |
| docs/IDE-INTEGRATIONS.md | Adds a status banner positioning the page as a supporting setup reference. |
| docs/benchmarks/README.md | Repairs benchmark research reference to the archived internal-notes location. |
| .github/wiki/Roadmap.md | Adds a status banner clarifying roadmap is planning/supporting context, not setup/API truth. |
| docs/archive/internal-notes/README.md | Introduces an archive index explaining purpose and what the archive contains. |
| docs/archive/internal-notes/BENCHMARK_PATCH_PLAN_2026-03-24.md | Archives benchmark patch planning material under internal notes. |
| docs/archive/internal-notes/BENCHMARK_HARNESS_SPEC_2026-03-24.md | Archives benchmark harness specification material under internal notes. |
| docs/archive/internal-notes/ultra-edit/00-overview.md | Archives internal “Ultra Edit” overview packet. |
| docs/archive/internal-notes/ultra-edit/01-adversary.md | Archives internal “Ultra Edit” adversary/threat model notes. |
| docs/archive/internal-notes/ultra-edit/02-contracts.md | Archives internal “Ultra Edit” contracts notes. |
| docs/archive/internal-notes/ultra-edit/03-tests.md | Archives internal “Ultra Edit” test matrix notes. |
| docs/archive/internal-notes/ultra-edit/04-vision.md | Archives internal “Ultra Edit” vision/oracle notes. |
| docs/archive/internal-notes/ultra-edit/05-transaction-model.md | Archives internal “Ultra Edit” transaction model notes. |
| docs/archive/internal-notes/ultra-edit/06-rollout.md | Archives internal “Ultra Edit” rollout plan notes. |
| docs/archive/internal-notes/ultra-edit/07-semantic-targeting.md | Archives internal “Ultra Edit” semantic targeting notes. |
| docs/archive/internal-notes/ultra-edit/08-phase1-code-map.md | Archives internal “Ultra Edit” phase 1 code map notes. |
| docs/archive/internal-notes/ultra-edit/09-phase1-build-cut.md | Archives internal “Ultra Edit” phase 1 build cut notes. |
| docs/archive/internal-notes/SURGICAL_V2_HARDENING.md | Archives internal hardening report for surgical v2 + apply_batch. |
| docs/archive/internal-notes/SURGICAL_V2_CONTRACTS.md | Archives internal contract/design notes for surgical v2 tools. |
| docs/archive/internal-notes/SURGICAL_V2_BUILD_REPORT.md | Archives internal build report for surgical v2 work. |
| docs/archive/internal-notes/SURGICAL_CONTEXT_HARDENING.md | Archives internal hardening report for surgical_context + apply. |
| docs/archive/internal-notes/SURGICAL_CONTEXT_CONTRACTS.md | Archives internal contracts/spec notes for surgical_context + apply. |
| docs/archive/internal-notes/SURGICAL_BUILD_REPORT.md | Archives internal build report for surgical tooling. |
| docs/archive/internal-notes/LANDING_COPY_V0_6_1.md | Archives internal landing/positioning copy draft. |
| docs/archive/internal-notes/CORTEX_V04_VISION.md | Archives internal v0.4.0 vision/analysis notes. |
| docs/archive/internal-notes/CORTEX_V04_TESTS.md | Archives internal v0.4.0 golden test notes. |
| docs/archive/internal-notes/CORTEX_V04_SYNTHESIS.md | Archives internal v0.4.0 synthesis notes. |
| docs/archive/internal-notes/CORTEX_V04_CONTRACTS.md | Archives internal v0.4.0 contracts notes. |
| docs/archive/internal-notes/CORTEX_V04_BUILD.md | Archives internal v0.4.0 build report notes. |
| docs/archive/internal-notes/CORTEX_V04_ADVERSARY.md | Archives internal v0.4.0 adversary notes. |
| docs/archive/internal-notes/CORTEX_ONDA1_TESTS.md | Archives internal ONDA 1 golden tests notes for surgical_context_v2/apply_batch. |
| docs/archive/internal-notes/CORTEX_ONDA1_CONTRACTS.md | Archives internal ONDA 1 contracts deliverable notes. |
| docs/archive/internal-notes/CORTEX_ONDA1_ADVERSARY.md | Archives internal ONDA 1 adversary summary notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
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.
Summary
docs/archive/internal-notes/Why
The repo had accumulated a lot of high-value internal artifacts, but they were sitting directly alongside the public onboarding docs. That made the public documentation surface feel noisier than it needed to be.
This PR keeps the material, but moves it out of the main lane and makes the user-facing path much easier to follow.
Included
USE-CASES.mddocs/IDE-INTEGRATIONS.mddocs/OPENCLAW-NATIVE-FASTPATH.md.github/wiki/Roadmap.mddocs/wiki/src/benchmarks.mddocs/benchmarks/README.mdNotes
README.md, wiki entrypoints,EXAMPLES.md,CONTRIBUTING.md,SECURITY.md,CHANGELOG.md, anddocs/deployment.md