ARCLUX Progress — Environment Gotchas
Termux, tsconfig, Webpack, version-pinning quirks. See PROGRES.md for the index.Problems that happened before — don’t repeat these
- Dead code piling up: 2 differently-named files doing the same thing
(
graph/resolveAlias.tsvsindexer/resolveAliases.ts) because of parallel sessions without sync. Lesson: ALWAYScat/grepfirst before writing a new file that could overlap. The same class of risk existed forpackages/ui/graphColor.tsvstheme/graphColors.ts— cleaned up 2026-08-14 (issue #11): the stub was deleted,theme/graphColors.tsis the single source. wc -lis misleading: a file with just the Apache 2.0 license header has a baseline of 8 lines even when empty. The “empty” threshold is≤9, not==0. Alwayscata suspicious file before recording its status in PROGRES.md.- Duplicate license headers: there was once a file with 2 headers (old MIT + new Apache stacked) from a mid-stream license change without removing the old header first. Already cleaned up manually.
- Long scripts can silently fail partway through: the CommandPalette
session once failed to write a file partway through a heredoc, but the
earlier steps (installing
cmdk, creatingfuzzyScore.ts) still succeeded — making it look “done” when it wasn’t complete. Lesson: after running a multi-step script, verify each step (catthe file /git log), don’t assume “ran” means “all succeeded”. - Termux quirks:
/tmpdoesn’t exist, Turbopack doesn’t run on arm64 (use--webpack), git push needs a Personal Access Token, not a password. - Don’t clone reference repos inside
~/arclux— they must be at the~root (~/git-truck,~/madge,~/opencode,~/research/*), outside the project. - Backticks inside double-quoted shell args get executed: a commit
message or
gh pr create --bodywritten with`code`spans inside double quotes is shell-substituted — the span is eaten and “command not found” noise lands in the message (PR #365, 2026-08-14; had to--amend+ force-push +--body-fileto clean up). Lesson: PR bodies go through--body-file <file>; commit messages throughgit commit -F -with a heredoc; never backticks in double-quoted shell text.
2026-08-03 — Running tsc from repo root gives false @/ alias errors for apps/web
npx tsc --noEmit -p . from ~/arclux (repo root) uses the ROOT
tsconfig.json, which has no @/* path alias configured — that alias only
exists in apps/web/tsconfig.json, scoped to that app. Running the root
check reports 100+ “Cannot find module ’@/…’” errors across nearly
every file in apps/web/, none of which are real. The correct check for
apps/web specifically is:
cd apps/web && npx tsc —noEmit
This was the root cause of issue #51 being filed as a false positive
(input-group.tsx reported as broken from a root-level check, shows zero
errors when checked correctly from apps/web/). If a check from root
surfaces a wall of @/ alias errors, re-run from apps/web/ before
concluding anything is actually broken.
2026-08-06 — main branch has protection rule, can’t push directly
git push origin main gets rejected with GH013: Repository rule violations... Changes must be made through a pull request, even after a
clean local fast-forward merge. Workaround: push the feature branch, open
a PR on GitHub, merge from there. Don’t assume a local merge to main is
enough to publish it.
2026-08-06 — GitHub PR merge can use a stale commit if merged before the push finishes propagating
Merging a PR on GitHub right after git push sometimes merges an earlier commit on that branch, not the latest one — happened twice today and silently reverted fixes to CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md back to an older, overwritten version. Always run ‘git diff main..<branch> —stat’ right before merging, and re-verify the actual file contents on main (not just git log) after every merge, especially for files edited more than once in the same PR chain.2026-08-06 — Stray branch-name text landed inside PROGRES.md content
Found literal lines ‘split/progres-status’, ’----’, and ‘main’ sitting inside PROGRES.md’s prose (not as code/comments) after a merge — looked like terminal output or branch names got pasted into a file edit by mistake. Always grep a file for suspicious bare words after any merge that touches a shared doc, not just diff —stat.2026-08-09 — npm install failed with corrupted lockfile; package.json still declares pnpm+turbo
Status: Not Started npm install was failing repo-wide with “Cannot read properties of null (reading matches)”. Fixed via rm -rf node_modules package-lock.json, npm cache clean —force, npm install. Separately: package.json currently declares packageManager pnpm@9.15.0 — project uses pnpm as established in TOOLING.md, this npm troubleshooting was likely done by a session unaware of that. Flagging so a future session does not assume npm without checking TOOLING.md first.2026-08-10 — Vitest does not support Jest-style —runInBand flag
Status: Done pnpm test — —runInBand fails since Vitest 4.1.10 has no such option. Plain pnpm test is correct for this project: 5 test files passed, 23 tests passed.2026-08-11 — GraphFocusView.tsx and GraphProvider.tsx had not been read since the PROGRES.md entry marking them unverified in-browser
Status: Done A much earlier decisions.md/status entry (GraphMenu consolidation session) explicitly flagged GraphFocusView.tsx as pushed near a chat context limit, typecheck-only, not visually verified in-browser. This session is the first time it was actually exercised by a real user against a real large-fan-in file (25 affected files) — both bugs found (dead back-button icon, silent 12-item cap) were exactly the kind of thing a typecheck-only “looks done” status hides. Lesson: when a PROGRES entry says “not yet visually verified,” treat any bug report against that component as plausible even if the code “looks” complete on read — do not assume the component is solid just because it compiled and was merged. main2026-08-13 — Two main-like branches causing sync confusion
Status: Not Started Repo has both ‘origin/main’ and ‘origin/ARCLUX.main’ as branches. This session repeatedly hit ‘fatal: couldn’t find remote ref main’ during git checkout/pull sequences, and packages/editor/ + packages/diagnostics/ appeared to vanish between commands even after being written and committed. Root cause suspected: local checkout/pull steps intermittently targeted or got confused between these two branches, leaving local main stale relative to origin/main while work was actually preserved on feature branches. Fix applied: always ‘git fetch origin’ then ‘git reset —hard origin/main’ before trusting local file listings, rather than assuming local main == remote main. Needs a real decision: rename or delete one of the two main-like branches so this class of bug can’t recur. docs/log-today-progress-v22026-08-13 — Default branch repo adalah ARCLUX.main, bukan main
Status: Not Started git remote show origin menunjukkan HEAD branch repo ini ARCLUX.main. Sempat push beberapa commit (scaffold platform layer + docs map) ke main tanpa sadar itu bukan branch default. Ketauan pas GitHub nawarin Compare antara main dan ARCLUX.main. Fix: isi main digabung ke ARCLUX.main. Selalu cek git remote show origin | grep ‘HEAD branch’ di awal sesi baru.2026-08-13 — Default branch repo adalah ARCLUX.main, bukan main
Status: Not Started git remote show origin menunjukkan HEAD branch repo ini ARCLUX.main. Sempat push beberapa commit (scaffold platform layer + docs map) ke main tanpa sadar itu bukan branch default. Ketauan pas GitHub nawarin Compare antara main dan ARCLUX.main. Fix: isi main digabung ke ARCLUX.main. Selalu cek git remote show origin | grep ‘HEAD branch’ di awal sesi baru.2026-08-13 — Repo default branch is ARCLUX.main, not main
git remote show origin menunjukkan HEAD branch repo ini adalah
ARCLUX.main, bukan main. Sempat push beberapa commit (platform
layer scaffold + docs map) ke main tanpa sadar itu bukan branch
default, jadi hasilnya nggak langsung kelihatan sebagai kerjaan utama di
GitHub. Ketauan pas GitHub nawarin “Compare” antara main dan
ARCLUX.main dan base-nya ke-set ARCLUX.main.
Fix: konten main digabung ke ARCLUX.main (jadi ARCLUX.main
sekarang superset). Selanjutnya kerja langsung dari ARCLUX.main.
Selalu cek dengan git remote show origin | grep "HEAD branch" di awal
sesi baru sebelum push, supaya nggak kejadian lagi.
ARCLUX.main
2026-08-14 — main vs ARCLUX.main divergence confirmed — work from ARCLUX.main
Status: Not Started CONFIRMED (previously only suspected): origin/main and origin/ARCLUX.main are NOT the same branch and have diverged significantly. ARCLUX.main is the actively-maintained branch (has packages/runtime/, 263 more files, collaborator work) and has already merged all of main’s history in (see commit ‘Merge pull request #320 from GSF-001/main’). main is stale/behind. Any session doing ‘git checkout main && git pull’ will get a stale tree missing packages/runtime/ and other recent work, causing false ‘file not found’ errors that look like data loss but are actually just being on the wrong branch. FIX: always work from ARCLUX.main going forward — ‘git checkout ARCLUX.main && git pull origin ARCLUX.main’ — until someone with repo admin access consolidates the two branches into one. Do not assume ‘main’ is current without checking origin/ARCLUX.main’s commit count first.2026-08-14 — RESOLVED: main deleted, only ARCLUX.main remains (issue #355)
Status: Done Verified viagit ls-remote origin + GitHub API: refs/heads/main no longer exists on the remote. Only ARCLUX.main remains, it is the default branch (origin/HEAD -> ARCLUX.main) and is protected. The divergence class from the 08-14 entry above cannot recur. Issue #355 can be closed. Working rule stays the same: work from ARCLUX.main.
2026-08-15 — Bare ‘docs/’ in .gitignore silently blocked docs-site/docs/* from ever being committed
Status: Done .gitignore had a bare ‘docs/’ pattern intended only for root’s docs/ (MCP tooling output, see the comment above it). Gitignore patterns without a leading slash match at ANY depth, so this silently ignored every file under docs-site/docs/ too — git add reported no error, files just never got staged. This caused PR #399 to merge without docs-site/docs/how-to-use.md even though the commit message claimed it was included; the file sat uncommitted on disk and the docs site never updated. Root cause found by noticing ‘git log —oneline — <path>’ returned empty after a claimed merge, then ‘git add’ throwing a silent ignored-file hint. Fixed by anchoring the pattern to /docs/ (root only). LESSON: after any docs-site/docs/* change, verify with ‘git log —oneline -1 — <path>’ after merge, don’t just trust the push/merge succeeding — gitignore can silently drop files with zero error output.2026-08-15 — CI failures caught late: MDX angle-bracket parsing + ESLint no-explicit-any/cascading-setState not checked before merge
Status: Done Two separate CI failures happened after merges this session because local verification only ran tsc —noEmit, never the full CI suite (pnpm run lint, docusaurus build): (1) docs-site/docs/how-to-use.md had bare <daemonId>/<port> placeholders — MDX parses < as JSX tag start, broke docs-build with ‘Expected a closing tag’. Fixed by escaping to </>. (2) Explorer.tsx’s allDiagnostics used any[] (3x no-explicit-any) and a second useEffect calling setState based on the first effect’s state (cascading-render lint rule). Fixed with a typed interface + useMemo instead of a second effect. LESSON: tsc —noEmit passing does NOT mean CI passes — ESLint and docs build are separate checks with different rules (no bare <text> in .md files under docs-site/docs/, no any, no setState-in-effect chains). Check ‘gh run list —limit 1 —json conclusion’ after every push that touches apps/web or docs-site/docs/, don’t assume merge success means CI green.2026-08-15 — TWO parallel doc sites exist: Mintlify (.app) and Docusaurus (.site) — adding a page needs BOTH
Status: Done arclux-os.mintlify.site is Docusaurus (docusaurus build, deployed to GitHub Pages via .github/workflows, nav controlled by docs-site/sidebars.js, pages live under docs-site/docs/.md). arclux-os.mintlify.app is actual Mintlify hosting (reads docs-site/docs.json for nav, pages live as root-level docs-site/.mdx files, e.g. docs-site/architecture.mdx not docs-site/docs/architecture.md). These are NOT the same site with two domains — they are two independently maintained doc systems that happen to look similar. Adding a new doc page requires: (1) the content file in BOTH locations (docs-site/docs/NAME.md for Docusaurus, docs-site/NAME.mdx for Mintlify), (2) registered in BOTH sidebars.js (Docusaurus) AND docs.json (Mintlify). Missing either causes a 404 on that specific site while the other works fine, which is confusing to debug without knowing both sites exist. GitHub Pages also needs to be manually enabled once via repo Settings > Pages > Source > GitHub Actions (was ‘currently disabled’, causing ‘Resource not accessible by integration’ on the deploy job even though the build job succeeded).2026-08-15 — CORRECTION: Mintlify (.app-style domain, docs.json) is the ACTIVE site, not Docusaurus
Status: Done Previous gotcha entry (this session) incorrectly assumed Docusaurus was the live site because a workflow builds it and deploys to GitHub Pages successfully. WRONG. Verified: docs-site/overview.mdx has title ‘Overview’ matching the live /overview URL path; docs-site/docs/index.md (Docusaurus) has title ‘ARCLUX Docs’ and no matching slug. Mintlify (docs.json + root-level docs-site/.mdx) is the actually-used, actually-linked-from-README site. Docusaurus (sidebars.js + docs-site/docs/.md, deployed via GitHub Pages) appears to be an unused/abandoned parallel setup — do NOT delete it yet without confirming with repo owner first, but do not trust it as the source of truth for ‘is this page live’ either. Next step: confirm with owner whether Docusaurus setup should be removed entirely to stop this confusion recurring.2026-08-16 — three.js SpriteMaterial sizeAttenuation:false: scale is NOT pixels — giant screen-covering quad
Tried to give the 3D hub badges a constant screen size withSpriteMaterial({ sizeAttenuation: false }) and sprite.scale.set(88, 22, 1). Result: the entire 3D view went white/gray at every zoom level (circles/links still faintly visible). Root cause: the sprite vertex shader does scale *= -mvPosition.z when sizeAttenuation is off, so the scale is multiplied by CAMERA DEPTH — an “88px” badge becomes a quad ~19,000 CSS px tall covering the whole viewport (screen px = scale * viewportHeight / (2*tan(fov/2))). sizeAttenuation:false is meant for near-pixel-sized sprites (values ~0.01-1), NOT arbitrary pixel scales. Fix: keep sizeAttenuation:true (world-space, perspective-correct) and size the sprite relative to the node (20x5 for a sphere r=4). Lesson: don’t trust “sizeAttenuation:false = pixels” from memory — read the shader (node_modules/three/src/renderers/shaders/ShaderLib/sprite.glsl.js) before using. KI-055.
2026-08-20 — Restored machine: stale node_modules + carried-over working-tree changes (NOT ours)
Machine state after restore broke tooling in ways that LOOK like code bugs but aren’t:-
Vitest 4’s rolldown has no native Termux binary — the bundler checks
process.platform === "android"but Termux reports"linux", so it falls back to wasm:@rolldown/binding-wasm32-wasi+ emnapi runtime must be present, otherwise vitest fails with “rolldown-binding.wasi.cjs missing”. Fix that worked:pnpm install --force(rebuilt the tree from the intact store at ~/.local/share/pnpm/store). Escape hatches if it recurs:NAPI_RS_NATIVE_LIBRARY_PATH/NAPI_RS_FORCE_WASI. -
pnpm store/node_modules version mismatch —
pnpm add -Dwfailed because node_modules was installed by a different pnpm major than the one on PATH. Same fix:pnpm install --force. -
Global
tsxbroken (missing esbuild binary) — always use./node_modules/.bin/tsxfrom repo root, never the global one. -
Carried-over working-tree changes are NOT ours — after restore,
git statusshowed: 3 modified files in packages/environment, 2 in packages/workspace, untrackedpackages/environment/ArcluxEnvironment.ts+.arclux-test, and 12 DELETED files under scripts/. None of these came from our session work — they were left by a previous session/machine state. Do NOT commit or “clean up” them without asking the repo owner first. Workflow used every time:git stash -u -- <my files>→ branch fromorigin/ARCLUX.main→ pop → stage ONLY my files.