Repository navigation
docs: bring every surface back in line with 0.13 and the macOS app - #252
Merged
Merged
Conversation
The vector store moved into SQLite and the Mac got an app; the docs kept describing the world before both. The two worst were not stylistic: - TEAM_DEPLOYMENT told operators to back up /data/chroma, which since 0.13 is the frozen rollback tree. Following it produced a backup with no index in it. The live store is /data/vectors. - SETUP_MACOS_NATIVE opened with "for full Metal acceleration you must run cix-server natively", which cix.app has made false — it ships a Metal server and installs it without a toolchain. That doc is now explicitly the from-source path, and the app leads everywhere a Mac install is described. Numbers were being copied doc-to-doc rather than measured, so the same CPU image was ~21 MB, ~40 MB and ~100 MB in three files. Every size here is now read from the source: Docker Hub reports 81 MB (amd64) and 73 MB (arm64) for the CPU image and 1077 MB for CUDA; the GitHub release reports 37.2 MB for the macOS runtime and 3.9 MB for the DMG. Also: CONFIG_REFERENCE calls itself the authoritative list and was missing nine variables; RELEASES knew two of the three tag streams and had no procedure for cutting the third; DASHBOARD predated the Runtime settings / Resources split and named two pages by labels the sidebar no longer uses; UPDATES said cix does not self-update, which the app does; SEARCH_ALGORITHM promised a transaction spanning the vector store and the FTS mirror, which is not possible across two database files and never was. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…store The docs page introduced cix.app as "a second way in", after the installer section whose native mode it has replaced — so a Mac visitor was routed into a from-source build (Go, Node, Xcode CLT) to get a server the app installs for them. The install section now opens with the app and says which of the following steps it has already done. The Storage table still described CIX_CHROMA_PERSIST_DIR as the vector store and had no row for the store that actually holds the vectors. Adds CIX_VECTORS_DIR, CIX_VECTOR_MMAP_SIZE, CIX_BIND_ADDR and the database-maintenance variables, plus the three admin route groups shipped since (resources, database, schedules). The landing page never mentioned the app at all, and its only resource claim was about the model — nothing told a prospective self-hoster what memory to budget, which since 0.13 is the good news: tens of megabytes at idle whatever the index size. Folded into the existing card rather than added as a seventh, which would have left a hole in a grid of three. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three doc comments justified their code by "the vector store is an in-memory database — chromem loads every document at startup and never evicts". That reason is gone, and each sat in a file whose neighbouring comments had already been corrected, so they read as contradictions: maintenance reclaims disk now, not RAM; VectorStoreUsage is a query rather than a free read of a process image; and Resources leads with system RSS precisely because the Go heap no longer describes the footprint. install-server.sh gets four informational lines on Apple Silicon. It still defaults to the from-source build there, and that default is unchanged — but announcing nothing about the app to someone who ran the one-liner is the same staleness this branch is removing from the docs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Aug 16, 2026
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.
Two shipped changes — the SQLite vector store (
server/v0.13.0) and cix.app (mac/v*) — never reached the documentation. This sweeps all of it: README,doc/, the site, the mac docs, the skills mirror, and the code comments that explain why a subsystem exists.The two that could cost someone something
doc/TEAM_DEPLOYMENT.mdtold operators to back up/data/chroma. Since 0.13 that is the frozen pre-migration tree kept for rollback; the live vectors are in/data/vectors. Following the doc produced a backup with no index in it.doc/SETUP_MACOS_NATIVE.mdopened with "for full Metal acceleration you must run cix-server natively". cix.app ships a Metal-accelerated server and installs it with no toolchain, so that is now false. The doc is explicitly the from-source path, and the app leads every place a Mac install is described — README Quick Start, the site, and an informational note ininstall-server.sh(whose default is unchanged).Numbers, measured rather than copied
The same CPU image was documented as ~21 MB, ~40 MB and ~100 MB in three files, because each was copied from another doc. Every size in this PR is read from the source: Docker Hub reports 81 MB (amd64) / 73 MB (arm64) for the CPU image and 1077 MB for CUDA; the GitHub release reports 37.2 MB for the macOS runtime and 3.9 MB for the DMG. Also corrected:
start_period(120 s → the real 600 s) and the VRAM baseline'sn_ctx(8192 → the actual default of 2048).Gaps closed
CONFIG_REFERENCE.mdCIX_DB_MAINTENANCE_*,CIX_DATA_DIR,CIX_LLAMA_CACHE_RAM, the tunnel set); resource table still promised "~1 GB idle"RELEASES.mdDASHBOARD.mdUPDATES.mdSEARCH_ALGORITHM.mdTROUBLESHOOTING.mdCIX_VECTOR_MMAP_SIZEmemory surpriseDEPRECATION_POLICY.mdCIX_CHROMA_PERSIST_DIRis now legacy-read-onlyPlus
MIGRATION_FROM_PYTHON.md(said the Go server uses chromem-go in JSON format — wrong engine, wrong format),DOCKER_TAGS.md(CPU image annotated "use withCIX_EMBEDDINGS_ENABLED=false" when it bundles the sidecar),CONTRIBUTING.md(Go 1.24, three CI workflows, nomac/orsite/in the tree),workspaces.mdand thecix-workspaceskill (namedchromem.Searchin the pipeline diagram).Code
maintenance.go,usage.goandResourcesSection.tsxstill justified themselves with "the vector store is an in-memory database — chromem loads every document at startup and never evicts". Each sat beside comments already corrected in earlier rounds, so they read as contradictions within one package.Verification
go build ./...and the touched packages' tests pass; the site builds;sync-skills.sh --checkis clean; the reordered install section and the landing grid were checked in a browser (heading order right, card grid still three-up).Not in this PR
Re-shooting the three dashboard screenshots (
site/public/img/, all from before the cream & ink rewrite) and the site reorganisation — both deliberately deferred.🤖 Generated with Claude Code