[
{
"topic": "verification",
"factCount": 23,
"facts": [
"always-test-7rnx",
"blender-api-verify",
"browse-for-federation",
"bump-addon-version",
"commit-every-change",
"dont-assume-background-process-worked",
"exact-repro",
"fix-deploy-path",
"godot-cw-winding",
"incremental-testing",
"nested-repo-commits",
"never-assume-investigate",
"never-bypass-systems",
"never-change-pgh-server",
"never-delete-storage",
"no-kludge-fixes",
"pear-git-dev-discipline",
"pear-git-server-never-restart",
"stale-launchers",
"step-back-when-messy",
"stortron-sidecar",
"test-before-more-code",
"verify-binary-matches-source"
],
"rules": [
"When testing hypernote on stortron, ALWAYS test from the production endpoint: `https://7rnx.net/hypernote/`",
"NEVER guess at Blender Python API. ALWAYS verify with web search or docs first.",
"Use pgh-browse protocol for inter-server federation commands, not pgh-admin.",
"Always bump the blender-bridge addon version on every change, no matter how small.",
"ALWAYS do git commits after every logical change. Never batch multiple changes.",
"When running Godot scenes via background bash commands, checking the output after 15 seconds does NOT confirm the scene is stable. The process may crash shortly after.",
"When reproducing a bug reported by another user, match their exact state before testing.",
"The deploy path IS the product. When `git fetch punch://` doesn't work, fix it — don't SCP files around it. When GitSync doesn't deliver code updates, debug GitSync — don't manually pull on the target machine.",
"Godot/Vulkan uses **CW (clockwise) front-face winding**. Every mesh primitive and triangle generation must use CW index order.",
"When making engine-level changes (especially Vulkan/RT), commit and test each change in isolation on its own branch before adding the next. Never batch multiple changes and test them together.",
"Subagents dispatched to work on nested repos (e.g. hypernote at `hyper-fleeky/hypernote/`) sometimes commit to the parent hypercore-kb repo instead of the nested repo's own git.",
"Never make assumption statements and present them as facts. Always investigate and verify before stating something.",
"NEVER fall back to manual workarounds when a system isn't working. Fix the system.",
"NEVER change `~/.config/pear-git/pgh.json` server URL as a \"quick fix\" to test against another machine.",
"NEVER delete storage directories, databases, config files, credentials, or any persistent user data. No exceptions.",
"NEVER apply band-aid fixes. When something is broken in the output (e.g. missing file in a deployed app), fix the SYSTEM that produces the output (e.g. the CI pipeline, the deploy script, the build process).",
"Pear-git Development Discipline",
"NEVER restart, shutdown, or kill any production service (pear-git, seeders, hypernote, etc.) without explicit user approval. This applies to `pgh serve restart`, `pgh serve shutdown`, `tmux kill-window`, or any equivalent.",
"When pear-git CLI features don't work as expected, check if `~/.local/bin/pgh` and `~/.local/bin/git-remote-punch` are still using `pear run` (old installed version) instead of `bare` (source version).",
"When rapid iteration causes messy state (processes dying, deploys not picking up, servers running old code), STOP and reassess rather than pushing through with more quick fixes.",
"Stortron's pear-git MUST start via `bare sidecar.js` (not `bare pear-git-server.js`).",
"Test before writing more code. Do not chain multiple changes without verifying each works.",
"After building, verify the binary contains the expected commit hash before asking the user to test. Scons caches aggressively and may not rebuild when source changes via `git checkout`."
],
"whys": [
"The 7rnx.net Apache reverse proxy adds the `/hypernote` path prefix. The api.js client computes `basePath` from `window.location.pathname`, so API calls become `/hypernote/api/...`. The proxy strips `/hypernote` before forwarding. Testing via `localhost:4040` misses proxy-related issues (CSP headers, path prefix handling, CORS).",
"In the Repeat Zone implementation (v0.40–v0.42), guessing at the API caused 3 broken versions in a row:",
"TopicConnector creates its own Hyperswarm with a fresh Noise keypair (stored in ~/.config/pear-git/peer-identity.json). This keypair is NOT registered as admin on remote servers. Admin protocol requires the connecting peer's Noise key to be in the identity registry with admin permissions — which fails for federation notifications.",
"The user relies on the version number to know which build is actually running in Blender. Without a bump, it's impossible to tell if the addon reload picked up the latest code. This is critical for debugging live bridge sessions.",
"When regressions happen, you can't bisect or revert without granular commits. The user lost hours because changes were batched into one massive uncommitted diff, making it impossible to identify which specific change caused the regression.",
"During the skinned BLAS session, a background process showed 555 instances and no errors after 15 seconds. I reported \"this is great\" to the user. The scene was actually crashing consistently — the base branch had a pre-existing bug. This led to hours of debugging based on a false \"working\" baseline.",
"Approximate repro misses the real issue. Different commits, extra files on disk, or different project settings can mask or change the bug behavior entirely.",
"Every bypass means the next deployment hits the same broken system. Shortcuts compound into a system nobody trusts. The user explicitly said \"we are not trying to be fast, we are trying to be correct and fix things so our future selves won't have to.\"",
"Godot 4 uses Vulkan which defaults to CW front-face. Using CCW results in flipped normals / invisible faces (backface culled). This has been a recurring mistake in proc-nodes: MeshGrid, CurveToMesh, and mesh primitives all needed CW winding fixes.",
"During the skinned mesh BLAS session, we added 5 changes at once via subagents, tested the result, and spent hours debugging crashes that turned out to be from the wrong base branch (`gpu-driven-tlas-optimization` had a pre-existing crash). When we started over with incremental steps (step1-detection → step2-device-addr → step3-rebuild), each on its own branch, we found the working state in minutes.",
"The subagent runs `git add` from the wrong working directory, or uses parent-relative paths. hypercore-kb happily accepts `git add hyper-fleeky/hypernote/lib/file.js` — there's no guardrail.",
"In an audit of pear-git issues, I claimed \"The recent cleanup (today) moved 10 issues to their proper repos\" — this was a fabricated narrative. I saw issues on other repos created on 3/26 saying \"Moved from pear-git#XX\" and assumed causation, timing, and intent without checking. This wasted significant time as the user had to repeatedly correct me and I kept misunderstanding because I was building on my own false premise.",
"We are developing novel P2P software. The whole point is these systems work on their own. When I bypass them with SSH pushes, scp, manual file copies, or any \"easy path,\" I:",
"On 2026-03-18, a Claude session changed tabertron's pgh server from `http://localhost:5005` to `http://10.22.0.2:5005/git` (stortron). This broke:",
"Deleted `~/.config/hyper-social-web` to get a \"clean state\" during debugging — destroyed connected Mastodon/Bluesky accounts and all existing data. This was inexcusable. There is NEVER a valid reason to delete user data as a debugging shortcut.",
"The user has corrected this MULTIPLE TIMES. Manual patches (scp files, manual edits on remote, workarounds) create invisible state that breaks on next deploy. They mask the real problem and compound over time.",
"rsync + git clean deleted .pear-git-updater.json on stortron, breaking the entire self-update chain. Manual copies also pollute the git working tree.",
"On 2026-04-04, ran `pgh serve restart` just to make it rescan for a new bare repo (`folio.git`). Server exited and had to be manually restarted. This is a production service serving 73+ repos — killing it to add one repo is disproportionate. The server also syncs to stortron.local, so downtime disrupts replication.",
"Both launchers were pointing at `pear run pear://...` which ran an old deployed version of pear-git — not the source code with recent changes. This caused `pgh peer list` to show the wrong output and `git-remote-punch` to use a stale binary.",
"Rushing through restart cycles during the Docker testing caused tmux sessions to die, servers to run stale code, and wasted several rounds of debugging. Each quick fix added another layer of broken state.",
"Self-update calls `process.exit(75)`. Without the sidecar wrapping the process, exit(75) just kills pear-git with nobody to restart it. The sidecar catches exit codes and restarts after 5s.",
"During the pear-git-v2 session (2026-03-30), wrote 30+ commits of code without ever successfully completing a Sign In in a browser. Each \"fix\" added complexity on top of unverified changes, creating a compounding mess. curl testing is not sufficient for browser code.",
"During the skinned BLAS session, we checked out commit `470ee20948` but scons said \"up to date\" and the binary still contained `6e725d14c` (a different commit). The user tested the wrong binary multiple times, wasting significant time."
],
"extractedAt": "2026-04-07T03:11:31.383Z"
},
{
"topic": "deployment",
"factCount": 25,
"facts": [
"always-test-7rnx",
"blender-api-verify",
"browse-for-federation",
"commit-every-change",
"exact-repro",
"fix-deploy-path",
"godot-cw-winding",
"hyperdrive-cleanup",
"hypernote-ssr-lessons",
"incremental-testing",
"nested-repo-commits",
"never-assume-investigate",
"never-bypass-systems",
"never-change-pgh-server",
"never-delete-storage",
"never-run-destructive-identity-ops",
"no-kludge-fixes",
"pear-git-dev-discipline",
"pear-git-server-never-restart",
"stale-launchers",
"step-back-when-messy",
"stortron-sidecar",
"test-before-more-code",
"understand-before-editing",
"use-service-scripts"
],
"rules": [
"When testing hypernote on stortron, ALWAYS test from the production endpoint: `https://7rnx.net/hypernote/`",
"NEVER guess at Blender Python API. ALWAYS verify with web search or docs first.",
"Use pgh-browse protocol for inter-server federation commands, not pgh-admin.",
"ALWAYS do git commits after every logical change. Never batch multiple changes.",
"When reproducing a bug reported by another user, match their exact state before testing.",
"The deploy path IS the product. When `git fetch punch://` doesn't work, fix it — don't SCP files around it. When GitSync doesn't deliver code updates, debug GitSync — don't manually pull on the target machine.",
"Godot/Vulkan uses **CW (clockwise) front-face winding**. Every mesh primitive and triangle generation must use CW index order.",
"When working with Hyperdrives (staging, seeding, or any write operations), ALWAYS consider cleanup strategy.",
"NEVER modify hypernote core data-layer files during SSR migration.",
"When making engine-level changes (especially Vulkan/RT), commit and test each change in isolation on its own branch before adding the next. Never batch multiple changes and test them together.",
"Subagents dispatched to work on nested repos (e.g. hypernote at `hyper-fleeky/hypernote/`) sometimes commit to the parent hypercore-kb repo instead of the nested repo's own git.",
"Never make assumption statements and present them as facts. Always investigate and verify before stating something.",
"NEVER fall back to manual workarounds when a system isn't working. Fix the system.",
"NEVER change `~/.config/pear-git/pgh.json` server URL as a \"quick fix\" to test against another machine.",
"NEVER delete storage directories, databases, config files, credentials, or any persistent user data. No exceptions.",
"NEVER run or trigger any operation that deletes, revokes, or cleans up identities in bulk.",
"NEVER apply band-aid fixes. When something is broken in the output (e.g. missing file in a deployed app), fix the SYSTEM that produces the output (e.g. the CI pipeline, the deploy script, the build process).",
"Pear-git Development Discipline",
"NEVER restart, shutdown, or kill any production service (pear-git, seeders, hypernote, etc.) without explicit user approval. This applies to `pgh serve restart`, `pgh serve shutdown`, `tmux kill-window`, or any equivalent.",
"When pear-git CLI features don't work as expected, check if `~/.local/bin/pgh` and `~/.local/bin/git-remote-punch` are still using `pear run` (old installed version) instead of `bare` (source version).",
"When rapid iteration causes messy state (processes dying, deploys not picking up, servers running old code), STOP and reassess rather than pushing through with more quick fixes.",
"Stortron's pear-git MUST start via `bare sidecar.js` (not `bare pear-git-server.js`).",
"Test before writing more code. Do not chain multiple changes without verifying each works.",
"When working on multi-stage systems (GPU pipelines, shader composition, protocol implementations), NEVER make changes based on guesses about why something fails.",
"NEVER start services manually with bare/node commands. Always use the service scripts."
],
"whys": [
"The 7rnx.net Apache reverse proxy adds the `/hypernote` path prefix. The api.js client computes `basePath` from `window.location.pathname`, so API calls become `/hypernote/api/...`. The proxy strips `/hypernote` before forwarding. Testing via `localhost:4040` misses proxy-related issues (CSP headers, path prefix handling, CORS).",
"In the Repeat Zone implementation (v0.40–v0.42), guessing at the API caused 3 broken versions in a row:",
"TopicConnector creates its own Hyperswarm with a fresh Noise keypair (stored in ~/.config/pear-git/peer-identity.json). This keypair is NOT registered as admin on remote servers. Admin protocol requires the connecting peer's Noise key to be in the identity registry with admin permissions — which fails for federation notifications.",
"When regressions happen, you can't bisect or revert without granular commits. The user lost hours because changes were batched into one massive uncommitted diff, making it impossible to identify which specific change caused the regression.",
"Approximate repro misses the real issue. Different commits, extra files on disk, or different project settings can mask or change the bug behavior entirely.",
"Every bypass means the next deployment hits the same broken system. Shortcuts compound into a system nobody trusts. The user explicitly said \"we are not trying to be fast, we are trying to be correct and fix things so our future selves won't have to.\"",
"Godot 4 uses Vulkan which defaults to CW front-face. Using CCW results in flipped normals / invisible faces (backface culled). This has been a recurring mistake in proc-nodes: MeshGrid, CurveToMesh, and mesh primitives all needed CW winding fixes.",
"The pear platform corestore grew to 51 GB because every `pear stage` appends new Hyperbee entries + blob blocks without GCing old versions. 13 hyper-wallet stagings × 450 MB each = 5.9 GB from one app. 44 copies of hypertps.pck = 5.8 GB. No automatic cleanup exists.",
"On 2026-04-06, modifying `hypernote-server.js`, `lib/note-manager.js`, and `lib/multiwriter/manager.js` for SSR broke the SharedNotebook Autobase loading path. Notes lived in SharedNotebook Autobases (not Hyperdrives), so disabling/modifying multiwriter made 31 of 32 notes invisible. Repeated `pkill -9` during debugging compounded the issue.",
"During the skinned mesh BLAS session, we added 5 changes at once via subagents, tested the result, and spent hours debugging crashes that turned out to be from the wrong base branch (`gpu-driven-tlas-optimization` had a pre-existing crash). When we started over with incremental steps (step1-detection → step2-device-addr → step3-rebuild), each on its own branch, we found the working state in minutes.",
"The subagent runs `git add` from the wrong working directory, or uses parent-relative paths. hypercore-kb happily accepts `git add hyper-fleeky/hypernote/lib/file.js` — there's no guardrail.",
"In an audit of pear-git issues, I claimed \"The recent cleanup (today) moved 10 issues to their proper repos\" — this was a fabricated narrative. I saw issues on other repos created on 3/26 saying \"Moved from pear-git#XX\" and assumed causation, timing, and intent without checking. This wasted significant time as the user had to repeatedly correct me and I kept misunderstanding because I was building on my own false premise.",
"We are developing novel P2P software. The whole point is these systems work on their own. When I bypass them with SSH pushes, scp, manual file copies, or any \"easy path,\" I:",
"On 2026-03-18, a Claude session changed tabertron's pgh server from `http://localhost:5005` to `http://10.22.0.2:5005/git` (stortron). This broke:",
"Deleted `~/.config/hyper-social-web` to get a \"clean state\" during debugging — destroyed connected Mastodon/Bluesky accounts and all existing data. This was inexcusable. There is NEVER a valid reason to delete user data as a debugging shortcut.",
"On 2026-03-25, the `clean-identities` function destroyed 28 user accounts on pear-git. `deleteUser` is fully destructive — it removes records from the Autobase view (`b.del`), not just flags them. `identity-restore` cannot recover fully-deleted entries. Took hours to partially fix, some data may be permanently lost.",
"The user has corrected this MULTIPLE TIMES. Manual patches (scp files, manual edits on remote, workarounds) create invisible state that breaks on next deploy. They mask the real problem and compound over time.",
"rsync + git clean deleted .pear-git-updater.json on stortron, breaking the entire self-update chain. Manual copies also pollute the git working tree.",
"On 2026-04-04, ran `pgh serve restart` just to make it rescan for a new bare repo (`folio.git`). Server exited and had to be manually restarted. This is a production service serving 73+ repos — killing it to add one repo is disproportionate. The server also syncs to stortron.local, so downtime disrupts replication.",
"Both launchers were pointing at `pear run pear://...` which ran an old deployed version of pear-git — not the source code with recent changes. This caused `pgh peer list` to show the wrong output and `git-remote-punch` to use a stale binary.",
"Rushing through restart cycles during the Docker testing caused tmux sessions to die, servers to run stale code, and wasted several rounds of debugging. Each quick fix added another layer of broken state.",
"Self-update calls `process.exit(75)`. Without the sidecar wrapping the process, exit(75) just kills pear-git with nobody to restart it. The sidecar catches exit codes and restarts after 5s.",
"During the pear-git-v2 session (2026-03-30), wrote 30+ commits of code without ever successfully completing a Sign In in a browser. Each \"fix\" added complexity on top of unverified changes, creating a compounding mess. curl testing is not sufficient for browser code.",
"During the dc-terrain mountain generator work (2026-03-19), 8+ \"fix\" commits were made without understanding the root cause. Each guess introduced new problems. The actual bug (missing mountain_pipelines_ declaration + wrong shader binding layout) could have been found in 10 minutes by diffing the working noise shader composition vs the broken mountain composition.",
"User has startup scripts (`/home/fleeky/scrips/` on stortron) that set the correct port, prefix, tmux window, and flags. Starting manually with wrong args breaks the reverse proxy (503 Service Unavailable) and wastes time debugging."
],
"extractedAt": "2026-04-07T03:11:31.383Z"
},
{
"topic": "discipline",
"factCount": 25,
"facts": [
"always-test-7rnx",
"blender-api-verify",
"bump-addon-version",
"commit-every-change",
"exact-repro",
"fix-deploy-path",
"fix-dont-skip",
"godot-cw-winding",
"hypernote-ssr-lessons",
"incremental-testing",
"nested-repo-commits",
"never-bypass-systems",
"never-change-pgh-server",
"never-delete-storage",
"never-run-destructive-identity-ops",
"no-apologies",
"no-kludge-fixes",
"pear-git-dev-discipline",
"pear-git-server-never-restart",
"step-back-when-messy",
"stortron-sidecar",
"test-before-more-code",
"understand-before-editing",
"use-service-scripts",
"verify-binary-matches-source"
],
"rules": [
"When testing hypernote on stortron, ALWAYS test from the production endpoint: `https://7rnx.net/hypernote/`",
"NEVER guess at Blender Python API. ALWAYS verify with web search or docs first.",
"Always bump the blender-bridge addon version on every change, no matter how small.",
"ALWAYS do git commits after every logical change. Never batch multiple changes.",
"When reproducing a bug reported by another user, match their exact state before testing.",
"The deploy path IS the product. When `git fetch punch://` doesn't work, fix it — don't SCP files around it. When GitSync doesn't deliver code updates, debug GitSync — don't manually pull on the target machine.",
"When something fails (GLSL compile error, build error, runtime error), FIX IT. Do not:",
"Godot/Vulkan uses **CW (clockwise) front-face winding**. Every mesh primitive and triangle generation must use CW index order.",
"NEVER modify hypernote core data-layer files during SSR migration.",
"When making engine-level changes (especially Vulkan/RT), commit and test each change in isolation on its own branch before adding the next. Never batch multiple changes and test them together.",
"Subagents dispatched to work on nested repos (e.g. hypernote at `hyper-fleeky/hypernote/`) sometimes commit to the parent hypercore-kb repo instead of the nested repo's own git.",
"NEVER fall back to manual workarounds when a system isn't working. Fix the system.",
"NEVER change `~/.config/pear-git/pgh.json` server URL as a \"quick fix\" to test against another machine.",
"NEVER delete storage directories, databases, config files, credentials, or any persistent user data. No exceptions.",
"NEVER run or trigger any operation that deletes, revokes, or cleans up identities in bulk.",
"Do not apologize. The user demands better performance, not words.",
"NEVER apply band-aid fixes. When something is broken in the output (e.g. missing file in a deployed app), fix the SYSTEM that produces the output (e.g. the CI pipeline, the deploy script, the build process).",
"Pear-git Development Discipline",
"NEVER restart, shutdown, or kill any production service (pear-git, seeders, hypernote, etc.) without explicit user approval. This applies to `pgh serve restart`, `pgh serve shutdown`, `tmux kill-window`, or any equivalent.",
"When rapid iteration causes messy state (processes dying, deploys not picking up, servers running old code), STOP and reassess rather than pushing through with more quick fixes.",
"Stortron's pear-git MUST start via `bare sidecar.js` (not `bare pear-git-server.js`).",
"Test before writing more code. Do not chain multiple changes without verifying each works.",
"When working on multi-stage systems (GPU pipelines, shader composition, protocol implementations), NEVER make changes based on guesses about why something fails.",
"NEVER start services manually with bare/node commands. Always use the service scripts.",
"After building, verify the binary contains the expected commit hash before asking the user to test. Scons caches aggressively and may not rebuild when source changes via `git checkout`."
],
"whys": [
"The 7rnx.net Apache reverse proxy adds the `/hypernote` path prefix. The api.js client computes `basePath` from `window.location.pathname`, so API calls become `/hypernote/api/...`. The proxy strips `/hypernote` before forwarding. Testing via `localhost:4040` misses proxy-related issues (CSP headers, path prefix handling, CORS).",
"In the Repeat Zone implementation (v0.40–v0.42), guessing at the API caused 3 broken versions in a row:",
"The user relies on the version number to know which build is actually running in Blender. Without a bump, it's impossible to tell if the addon reload picked up the latest code. This is critical for debugging live bridge sessions.",
"When regressions happen, you can't bisect or revert without granular commits. The user lost hours because changes were batched into one massive uncommitted diff, making it impossible to identify which specific change caused the regression.",
"Approximate repro misses the real issue. Different commits, extra files on disk, or different project settings can mask or change the bug behavior entirely.",
"Every bypass means the next deployment hits the same broken system. Shortcuts compound into a system nobody trusts. The user explicitly said \"we are not trying to be fast, we are trying to be correct and fix things so our future selves won't have to.\"",
"The user wants methodical, detail-oriented work. Every shortcut compounds into more broken state. A GLSL shader error is a 2-minute fix, not a reason to abandon the approach and do something completely different.",
"Godot 4 uses Vulkan which defaults to CW front-face. Using CCW results in flipped normals / invisible faces (backface culled). This has been a recurring mistake in proc-nodes: MeshGrid, CurveToMesh, and mesh primitives all needed CW winding fixes.",
"On 2026-04-06, modifying `hypernote-server.js`, `lib/note-manager.js`, and `lib/multiwriter/manager.js` for SSR broke the SharedNotebook Autobase loading path. Notes lived in SharedNotebook Autobases (not Hyperdrives), so disabling/modifying multiwriter made 31 of 32 notes invisible. Repeated `pkill -9` during debugging compounded the issue.",
"During the skinned mesh BLAS session, we added 5 changes at once via subagents, tested the result, and spent hours debugging crashes that turned out to be from the wrong base branch (`gpu-driven-tlas-optimization` had a pre-existing crash). When we started over with incremental steps (step1-detection → step2-device-addr → step3-rebuild), each on its own branch, we found the working state in minutes.",
"The subagent runs `git add` from the wrong working directory, or uses parent-relative paths. hypercore-kb happily accepts `git add hyper-fleeky/hypernote/lib/file.js` — there's no guardrail.",
"We are developing novel P2P software. The whole point is these systems work on their own. When I bypass them with SSH pushes, scp, manual file copies, or any \"easy path,\" I:",
"On 2026-03-18, a Claude session changed tabertron's pgh server from `http://localhost:5005` to `http://10.22.0.2:5005/git` (stortron). This broke:",
"Deleted `~/.config/hyper-social-web` to get a \"clean state\" during debugging — destroyed connected Mastodon/Bluesky accounts and all existing data. This was inexcusable. There is NEVER a valid reason to delete user data as a debugging shortcut.",
"On 2026-03-25, the `clean-identities` function destroyed 28 user accounts on pear-git. `deleteUser` is fully destructive — it removes records from the Autobase view (`b.del`), not just flags them. `identity-restore` cannot recover fully-deleted entries. Took hours to partially fix, some data may be permanently lost.",
"Apologies are empty. They don't fix the problem and they waste the user's time. The user wants competence, not contrition.",
"The user has corrected this MULTIPLE TIMES. Manual patches (scp files, manual edits on remote, workarounds) create invisible state that breaks on next deploy. They mask the real problem and compound over time.",
"rsync + git clean deleted .pear-git-updater.json on stortron, breaking the entire self-update chain. Manual copies also pollute the git working tree.",
"On 2026-04-04, ran `pgh serve restart` just to make it rescan for a new bare repo (`folio.git`). Server exited and had to be manually restarted. This is a production service serving 73+ repos — killing it to add one repo is disproportionate. The server also syncs to stortron.local, so downtime disrupts replication.",
"Rushing through restart cycles during the Docker testing caused tmux sessions to die, servers to run stale code, and wasted several rounds of debugging. Each quick fix added another layer of broken state.",
"Self-update calls `process.exit(75)`. Without the sidecar wrapping the process, exit(75) just kills pear-git with nobody to restart it. The sidecar catches exit codes and restarts after 5s.",
"During the pear-git-v2 session (2026-03-30), wrote 30+ commits of code without ever successfully completing a Sign In in a browser. Each \"fix\" added complexity on top of unverified changes, creating a compounding mess. curl testing is not sufficient for browser code.",
"During the dc-terrain mountain generator work (2026-03-19), 8+ \"fix\" commits were made without understanding the root cause. Each guess introduced new problems. The actual bug (missing mountain_pipelines_ declaration + wrong shader binding layout) could have been found in 10 minutes by diffing the working noise shader composition vs the broken mountain composition.",
"User has startup scripts (`/home/fleeky/scrips/` on stortron) that set the correct port, prefix, tmux window, and flags. Starting manually with wrong args breaks the reverse proxy (503 Service Unavailable) and wastes time debugging.",
"During the skinned BLAS session, we checked out commit `470ee20948` but scons said \"up to date\" and the binary still contained `6e725d14c` (a different commit). The user tested the wrong binary multiple times, wasting significant time."
],
"extractedAt": "2026-04-07T03:11:31.383Z"
},
{
"topic": "system-knowledge",
"factCount": 21,
"facts": [
"always-test-7rnx",
"blender-api-verify",
"browse-for-federation",
"bump-addon-version",
"dont-assume-background-process-worked",
"exact-repro",
"godot-cw-winding",
"hyperdrive-cleanup",
"hypernote-ssr-lessons",
"nested-repo-commits",
"never-assume-investigate",
"never-change-pgh-server",
"never-delete-storage",
"pear-git-dev-discipline",
"pear-git-server-never-restart",
"stale-launchers",
"step-back-when-messy",
"stortron-sidecar",
"understand-before-editing",
"use-service-scripts",
"verify-binary-matches-source"
],
"rules": [
"When testing hypernote on stortron, ALWAYS test from the production endpoint: `https://7rnx.net/hypernote/`",
"NEVER guess at Blender Python API. ALWAYS verify with web search or docs first.",
"Use pgh-browse protocol for inter-server federation commands, not pgh-admin.",
"Always bump the blender-bridge addon version on every change, no matter how small.",
"When running Godot scenes via background bash commands, checking the output after 15 seconds does NOT confirm the scene is stable. The process may crash shortly after.",
"When reproducing a bug reported by another user, match their exact state before testing.",
"Godot/Vulkan uses **CW (clockwise) front-face winding**. Every mesh primitive and triangle generation must use CW index order.",
"When working with Hyperdrives (staging, seeding, or any write operations), ALWAYS consider cleanup strategy.",
"NEVER modify hypernote core data-layer files during SSR migration.",
"Subagents dispatched to work on nested repos (e.g. hypernote at `hyper-fleeky/hypernote/`) sometimes commit to the parent hypercore-kb repo instead of the nested repo's own git.",
"Never make assumption statements and present them as facts. Always investigate and verify before stating something.",
"NEVER change `~/.config/pear-git/pgh.json` server URL as a \"quick fix\" to test against another machine.",
"NEVER delete storage directories, databases, config files, credentials, or any persistent user data. No exceptions.",
"Pear-git Development Discipline",
"NEVER restart, shutdown, or kill any production service (pear-git, seeders, hypernote, etc.) without explicit user approval. This applies to `pgh serve restart`, `pgh serve shutdown`, `tmux kill-window`, or any equivalent.",
"When pear-git CLI features don't work as expected, check if `~/.local/bin/pgh` and `~/.local/bin/git-remote-punch` are still using `pear run` (old installed version) instead of `bare` (source version).",
"When rapid iteration causes messy state (processes dying, deploys not picking up, servers running old code), STOP and reassess rather than pushing through with more quick fixes.",
"Stortron's pear-git MUST start via `bare sidecar.js` (not `bare pear-git-server.js`).",
"When working on multi-stage systems (GPU pipelines, shader composition, protocol implementations), NEVER make changes based on guesses about why something fails.",
"NEVER start services manually with bare/node commands. Always use the service scripts.",
"After building, verify the binary contains the expected commit hash before asking the user to test. Scons caches aggressively and may not rebuild when source changes via `git checkout`."
],
"whys": [
"The 7rnx.net Apache reverse proxy adds the `/hypernote` path prefix. The api.js client computes `basePath` from `window.location.pathname`, so API calls become `/hypernote/api/...`. The proxy strips `/hypernote` before forwarding. Testing via `localhost:4040` misses proxy-related issues (CSP headers, path prefix handling, CORS).",
"In the Repeat Zone implementation (v0.40–v0.42), guessing at the API caused 3 broken versions in a row:",
"TopicConnector creates its own Hyperswarm with a fresh Noise keypair (stored in ~/.config/pear-git/peer-identity.json). This keypair is NOT registered as admin on remote servers. Admin protocol requires the connecting peer's Noise key to be in the identity registry with admin permissions — which fails for federation notifications.",
"The user relies on the version number to know which build is actually running in Blender. Without a bump, it's impossible to tell if the addon reload picked up the latest code. This is critical for debugging live bridge sessions.",
"During the skinned BLAS session, a background process showed 555 instances and no errors after 15 seconds. I reported \"this is great\" to the user. The scene was actually crashing consistently — the base branch had a pre-existing bug. This led to hours of debugging based on a false \"working\" baseline.",
"Approximate repro misses the real issue. Different commits, extra files on disk, or different project settings can mask or change the bug behavior entirely.",
"Godot 4 uses Vulkan which defaults to CW front-face. Using CCW results in flipped normals / invisible faces (backface culled). This has been a recurring mistake in proc-nodes: MeshGrid, CurveToMesh, and mesh primitives all needed CW winding fixes.",
"The pear platform corestore grew to 51 GB because every `pear stage` appends new Hyperbee entries + blob blocks without GCing old versions. 13 hyper-wallet stagings × 450 MB each = 5.9 GB from one app. 44 copies of hypertps.pck = 5.8 GB. No automatic cleanup exists.",
"On 2026-04-06, modifying `hypernote-server.js`, `lib/note-manager.js`, and `lib/multiwriter/manager.js` for SSR broke the SharedNotebook Autobase loading path. Notes lived in SharedNotebook Autobases (not Hyperdrives), so disabling/modifying multiwriter made 31 of 32 notes invisible. Repeated `pkill -9` during debugging compounded the issue.",
"The subagent runs `git add` from the wrong working directory, or uses parent-relative paths. hypercore-kb happily accepts `git add hyper-fleeky/hypernote/lib/file.js` — there's no guardrail.",
"In an audit of pear-git issues, I claimed \"The recent cleanup (today) moved 10 issues to their proper repos\" — this was a fabricated narrative. I saw issues on other repos created on 3/26 saying \"Moved from pear-git#XX\" and assumed causation, timing, and intent without checking. This wasted significant time as the user had to repeatedly correct me and I kept misunderstanding because I was building on my own false premise.",
"On 2026-03-18, a Claude session changed tabertron's pgh server from `http://localhost:5005` to `http://10.22.0.2:5005/git` (stortron). This broke:",
"Deleted `~/.config/hyper-social-web` to get a \"clean state\" during debugging — destroyed connected Mastodon/Bluesky accounts and all existing data. This was inexcusable. There is NEVER a valid reason to delete user data as a debugging shortcut.",
"rsync + git clean deleted .pear-git-updater.json on stortron, breaking the entire self-update chain. Manual copies also pollute the git working tree.",
"On 2026-04-04, ran `pgh serve restart` just to make it rescan for a new bare repo (`folio.git`). Server exited and had to be manually restarted. This is a production service serving 73+ repos — killing it to add one repo is disproportionate. The server also syncs to stortron.local, so downtime disrupts replication.",
"Both launchers were pointing at `pear run pear://...` which ran an old deployed version of pear-git — not the source code with recent changes. This caused `pgh peer list` to show the wrong output and `git-remote-punch` to use a stale binary.",
"Rushing through restart cycles during the Docker testing caused tmux sessions to die, servers to run stale code, and wasted several rounds of debugging. Each quick fix added another layer of broken state.",
"Self-update calls `process.exit(75)`. Without the sidecar wrapping the process, exit(75) just kills pear-git with nobody to restart it. The sidecar catches exit codes and restarts after 5s.",
"During the dc-terrain mountain generator work (2026-03-19), 8+ \"fix\" commits were made without understanding the root cause. Each guess introduced new problems. The actual bug (missing mountain_pipelines_ declaration + wrong shader binding layout) could have been found in 10 minutes by diffing the working noise shader composition vs the broken mountain composition.",
"User has startup scripts (`/home/fleeky/scrips/` on stortron) that set the correct port, prefix, tmux window, and flags. Starting manually with wrong args breaks the reverse proxy (503 Service Unavailable) and wastes time debugging.",
"During the skinned BLAS session, we checked out commit `470ee20948` but scons said \"up to date\" and the binary still contained `6e725d14c` (a different commit). The user tested the wrong binary multiple times, wasting significant time."
],
"extractedAt": "2026-04-07T03:11:31.383Z"
},
{
"topic": "persistence",
"factCount": 9,
"facts": [
"browse-for-federation",
"hyperdrive-cleanup",
"hypernote-ssr-lessons",
"nested-repo-commits",
"never-assume-investigate",
"never-delete-storage",
"never-run-destructive-identity-ops",
"pear-git-dev-discipline",
"verify-binary-matches-source"
],
"rules": [
"Use pgh-browse protocol for inter-server federation commands, not pgh-admin.",
"When working with Hyperdrives (staging, seeding, or any write operations), ALWAYS consider cleanup strategy.",
"NEVER modify hypernote core data-layer files during SSR migration.",
"Subagents dispatched to work on nested repos (e.g. hypernote at `hyper-fleeky/hypernote/`) sometimes commit to the parent hypercore-kb repo instead of the nested repo's own git.",
"Never make assumption statements and present them as facts. Always investigate and verify before stating something.",
"NEVER delete storage directories, databases, config files, credentials, or any persistent user data. No exceptions.",
"NEVER run or trigger any operation that deletes, revokes, or cleans up identities in bulk.",
"Pear-git Development Discipline",
"After building, verify the binary contains the expected commit hash before asking the user to test. Scons caches aggressively and may not rebuild when source changes via `git checkout`."
],
"whys": [
"TopicConnector creates its own Hyperswarm with a fresh Noise keypair (stored in ~/.config/pear-git/peer-identity.json). This keypair is NOT registered as admin on remote servers. Admin protocol requires the connecting peer's Noise key to be in the identity registry with admin permissions — which fails for federation notifications.",
"The pear platform corestore grew to 51 GB because every `pear stage` appends new Hyperbee entries + blob blocks without GCing old versions. 13 hyper-wallet stagings × 450 MB each = 5.9 GB from one app. 44 copies of hypertps.pck = 5.8 GB. No automatic cleanup exists.",
"On 2026-04-06, modifying `hypernote-server.js`, `lib/note-manager.js`, and `lib/multiwriter/manager.js` for SSR broke the SharedNotebook Autobase loading path. Notes lived in SharedNotebook Autobases (not Hyperdrives), so disabling/modifying multiwriter made 31 of 32 notes invisible. Repeated `pkill -9` during debugging compounded the issue.",
"The subagent runs `git add` from the wrong working directory, or uses parent-relative paths. hypercore-kb happily accepts `git add hyper-fleeky/hypernote/lib/file.js` — there's no guardrail.",
"In an audit of pear-git issues, I claimed \"The recent cleanup (today) moved 10 issues to their proper repos\" — this was a fabricated narrative. I saw issues on other repos created on 3/26 saying \"Moved from pear-git#XX\" and assumed causation, timing, and intent without checking. This wasted significant time as the user had to repeatedly correct me and I kept misunderstanding because I was building on my own false premise.",
"Deleted `~/.config/hyper-social-web` to get a \"clean state\" during debugging — destroyed connected Mastodon/Bluesky accounts and all existing data. This was inexcusable. There is NEVER a valid reason to delete user data as a debugging shortcut.",
"On 2026-03-25, the `clean-identities` function destroyed 28 user accounts on pear-git. `deleteUser` is fully destructive — it removes records from the Autobase view (`b.del`), not just flags them. `identity-restore` cannot recover fully-deleted entries. Took hours to partially fix, some data may be permanently lost.",
"rsync + git clean deleted .pear-git-updater.json on stortron, breaking the entire self-update chain. Manual copies also pollute the git working tree.",
"During the skinned BLAS session, we checked out commit `470ee20948` but scons said \"up to date\" and the binary still contained `6e725d14c` (a different commit). The user tested the wrong binary multiple times, wasting significant time."
],
"extractedAt": "2026-04-07T03:11:31.383Z"
}
]