docs: correct four claims that contradict the code, and add CLAUDE.md - #5
Merged
VamikaSinghal merged 2 commits intoAug 2, 2026
Conversation
Contributor
Author
|
thank you for accepting! |
Contributor
Author
|
@sarptandoven review pls |
… docs site/index.html contradicted itself on the same page: the Distribution paragraph said "ad-hoc signed ... not yet notarized" while the install steps directly below, the README, and site/downloads/latest.json all say Developer ID signed and notarized by Apple. Three sources agree, so the paragraph was the stale one. SETUP.md documented `unittest discover` as the test command. CI deliberately overrides that with pytest, because backend/tests/conftest.py -- which only pytest loads -- pins CORTEX_DB_PATH/CORTEX_VAULT_PATH to a throwaway temp dir at import time. Under `unittest discover` the suite binds to the default backend/data/Cortex.vault instead, persists across runs, and writes into the working tree. Matches SETUP.md to CI and says why. The CI comment justifying that choice claimed conftest.py "provides fixtures". It declares none; the import-time env isolation is the whole job, and it matters because backend.app.main builds a process-singleton store on first import. Corrected so the next reader doesn't inherit the wrong reason. docs/ARCHITECTURE.md hand-copied the MCP tool list and had drifted to 42 stale entries against 110 in TOOLS -- query_memory and expand, which docs/CMP_PROTOCOL.md references, were both absent. Replaced with the core ten, the group structure, and a pointer to mcp_tools.py as source of truth, rather than re-copying a list that will drift again. Also documents the tool-surface mechanism (Cursor caps at 40, ChatGPT at 128) and that surface is advertisement only, never authorization. Every tool name cited was verified present in mcp_tools.py. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M12nsqf2Mw9cvEBeRiDBv1
…les to learn Onboarding guidance for Claude Code sessions, focused on what is not discoverable from any single file: the two-server split and its parity footgun, vault-as-truth vs SQLite-as-disposable-index, the review approval gate, the CMP/SMP invariants, and the hosted control plane that is built but dormant in the local product. The load-bearing one: semantic near-dup, rerank, MMR and entity boost are all gated on provider != "hash", and hash is exactly what CI runs, since backend/requirements.txt does not install model2vec. A green CI run proves the deterministic skeleton, not the semantic system -- rerank_eval.py exits 0 with status=skipped when the model is absent, and only release packaging enforces it via CORTEX_REQUIRE_MODEL=1. Also records the two cross-cutting conventions that surprise people: the Python tests that assert on the text of Swift/HTML/CSS sources, and the docs-currency phrase gate. Drop this commit if the repo would rather not carry an agent-guidance file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M12nsqf2Mw9cvEBeRiDBv1
roshantaneja
force-pushed
the
fix/route-parity-and-doc-currency
branch
from
July 30, 2026 06:45
214848a to
0b31fe2
Compare
roshantaneja
changed the title
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
2 participants
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.
Docs-only. Two commits, independently droppable. All findings were verified against the code before writing; specifics below.
The route-parity test that was originally part of this PR has been dropped — this branch now carries only the documentation corrections.
1.
docs— four claims correctedsite/index.html:162site/downloads/latest.jsonall say Developer ID signed and notarized. Three sources agree.SETUP.mdunittest discoverconftest.py(only pytest loads it) pins the vault/DB to a temp dir at import time; underunittest discoverthe suite binds tobackend/data/Cortex.vaultand writes into the working tree..github/workflows/ci.ymlcommentbackend.app.mainbuilds a process-singleton store on first import.docs/ARCHITECTURE.mdTOOLSholds 110.query_memoryandexpand— both referenced bydocs/CMP_PROTOCOL.md— were absent.The tool list is replaced with the core ten, the group structure, and a pointer to
mcp_tools.pyas source of truth, rather than re-copying a list that will drift again. Also documents the tool-surface mechanism (Cursor caps at 40, ChatGPT at 128) and that surface is advertisement only, never authorization. Every tool name cited was verified present inmcp_tools.py.2.
docs— CLAUDE.mdOnboarding guidance for Claude Code sessions, covering what no single file teaches. The load-bearing entry: semantic near-dup, rerank, MMR and entity boost are all gated on
provider != "hash", andhashis exactly what CI runs, sincebackend/requirements.txtdoesn't installmodel2vec. A green CI run proves the deterministic skeleton, not the semantic system. That's a documented trade, not a bug — but it isn't written down anywhere a reader would find it.Drop this commit if the repo would rather not carry an agent-guidance file.
Verification
scripts/check_docs_current.py—status: okscripts/check_distribution_site.py—status: okscripts/retrieval_eval.py—status: okhttpx/starletteskew under Python 3.13 (TestClient(app)→Client.__init__() got an unexpected keyword argument 'app'), reproduced identically on a clean tree; CI pins 3.12.Findings flagged, not fixed
Surfaced while surveying the two HTTP planes; no code in this PR addresses them.
/v1/imports/detectis shadowed on the FastAPI plane by/v1/imports/{import_id}(main.py:1716), so a hostedGET /v1/imports/detectresolves to fetch-by-id withimport_id="detect"rather than 404ing. A real semantic divergence between the two servers. Worth a look independently of this PR.CortexStore—standalone_server.py(stdlib, what the packaged macOS app launches) andmain.py(FastAPI, dev + hosted plane).test_fastapi_contract.pyandtest_standalone_server.pyeach exercise only their own surface, and thescripts/*_eval.pygates driveCortexStorein-process, so an endpoint wired into only one plane ships green while the other 404s. A parity gate would close this; it isn't in this PR.test_macos_ui_quality_contract.py::MacOSSignInQualityContractTests::test_native_apple_button_is_full_width_and_entitlement_gatedfails onmaintoday — it assertshasAppleSignInEntitlementappears inCortexCloudAuth.swiftand it doesn't. Out of scope.Deliberately not touched
site/downloads/latest.jsonis at build 51 whileInfo.plistis at 52. Regenerating it by hand would advertise a release tag/artifact that may not be uploaded — that belongs topackage_release.sh.api.trydoppl.com(status/.upptimerc.yml,deploy/macmini/setup.sh) vsapi.signindoppl.com(deploy/README.md,cortex.env.example). I don't know which is correct.site/downloads/distribution.jsonstale at build 22.🤖 Generated with Claude Code
https://claude.ai/code/session_01Aqpb9sHJt5A6UdotSR9Mcy