docs: refresh gh-pages and document technical constants (#107)

[tavateva]

Closes #107.
References #51, #104, #105, #106.

Summary

Adds a Reference section to the mkdocs documentation with a new
documentation/docs/reference/technical-constants.md page that
documents the hardcoded file explorer limits introduced by the #51
out-of-memory mitigation stack. Also adds a short user-visible
"Large Folder Behavior" section to the docs index and a plugin-author
note about the changed directory-broadcast payload.

The gh-pages branch is auto-generated by .github/workflows/build-docs.yml
from documentation/ on main, so this PR targets main rather than
editing gh-pages directly.

Constants documented

All values extracted from src/main/event-handlers/filesystem.ts
(lines 8-12):

Constant	Value	Introduced
FILE_EXPLORER_WATCH_DEPTH	6	#104
FILE_EXPLORER_WATCH_LIMIT	100_000	#104
IGNORED_PATH_SEGMENTS	{node_modules, __pycache__, venv} plus any .-prefixed segment	#104
FILE_EXPLORER_UPDATE_BATCH_LIMIT	500	#105
FILE_EXPLORER_UPDATE_INTERVAL_MS	100	#105

The plugin directory-broadcast change from #106 (empty nodes payload)
is also documented in the same reference page and cross-linked from
guide/plugins.md.

Each entry records: symbol name, current value, source file line,
rationale, user-visible behavior when the limit is reached, and
guidance on when to reconsider the value.

Files changed

• documentation/docs/reference/technical-constants.md (new)
• documentation/docs/index.md (new Reference link + Large Folder
  Behavior section)
• documentation/docs/guide/plugins.md (plugin directory broadcast
  note + reference link)
• documentation/mkdocs.yml (new Reference nav section)

Audit findings and out-of-scope

Setup, development, packaging, and runtime docs on main were
audited against the merged code. No existing pages carried claims
that are made wrong by #104/#105/#106, so no rewrites were needed
in this pass. The three existing mentions of "File Explorer panel"
in guide/plugins.md, guide/slicing.md, and guide/backproject.md
remain accurate for their drag-and-drop context.

Left out of scope for a follow-up:

• Any deeper end-to-end refresh of setup, packaging, and Python-side
  docs beyond the file-explorer and plugin-broadcast changes tied
  directly to Refresh gh-pages documentation and document technical constants #107's acceptance criteria.
• The broader plugin file API tracked by Lazy-load file explorer tree and plugin directory data #102, which will supersede
  the current empty-nodes broadcast.

Verification

• Grep confirms every documented value matches the current tree:
  grep -n 'FILE_EXPLORER_\|IGNORED_PATH_SEGMENTS' src/main/event-handlers/filesystem.ts.
• All internal markdown links resolve to files that exist in the
  branch.
• mkdocs build will run in CI via .github/workflows/build-docs.yml
  on push and redeploy the gh-pages branch automatically.

[tavateva]

Second sub-agent pass on the technical constants sweep. The extended commit (5078960) documents constants where the intent could be inferred directly from the code and existing PRs. The items below are ones where a short answer from den-sq (or Weaver) would let a follow-up PR either document them alongside the others or turn them into named constants first.

1. src/main/servers/file-server.ts:6 and src/main/servers/volume-server.ts:6 — port = 3000 (plugin file server) and port = 3001 (volume server) are lowercase locals with no env override. Are these worth promoting to named PLUGIN_FILE_SERVER_PORT / VOLUME_SERVER_PORT constants and/or making them env-configurable for users who already have services on 3000/3001?
2. src/main/servers/volume-server.ts:9 — VOLUME = 'ouroboros-volume' is duplicated as string literals in python/compose.yml, python/compose.dev.yml, python/ouroboros/common/volume_server_interface.py, and the compose file written by scripts/prepare-production-server.mjs. Any appetite for a single source of truth (env var or a generated compose fragment)?
3. src/renderer/src/contexts/ServerContext.tsx:41 — retryDelay = 5000 (5 s server health poll). Is 5 s the intended UX cadence, or should it be shorter given the connection banner drives visible UI state?
4. src/renderer/src/contexts/IFrameContext.tsx:23 — allowedOrigins is a prefix match (text.startsWith(item)), so http://localhost.evil.example would match http://localhost. Is the prefix match deliberate for port-suffix matching, and if so is it worth tightening to origin equality plus a separate port set?
5. src/renderer/src/routes/SlicesPage/SlicesPage.tsx:26 — SLICE_RENDER_PROPORTION = 0.008. Is 0.008 an empirically chosen ratio for the SlicesPage, and should it scale with rects.length rather than being flat (very short paths currently render every rect via the Math.floor(...) = 0 fallback)?
6. src/renderer/src/routes/SlicesPage/SlicesPage.tsx:30 — SLICE_STEP_NAME = 'SliceParallelPipelineStep' is coupled to a Python class name. Should the Python side expose a canonical step-name enum through the API so a rename doesn't silently break progress rows?
7. python/ouroboros/common/server.py:10-14 — HOST/PORT (127.0.0.1:8000) and DOCKER_HOST/DOCKER_PORT (0.0.0.0:8000). Should these be env-configurable (OUROBOROS_SERVER_HOST/OUROBOROS_SERVER_PORT) for users who need to run the desktop server on a non-default port?
8. python/ouroboros/common/volume_server_interface.py:4 — PLUGIN_NAME = 'main' is used as a subfolder on the shared volume and hard-coded into every copy_to_volume/copy_to_host/clear_plugin_folder call. Is this intentionally always 'main' from the Python side, or is there a planned per-plugin path scheme?
9. python/ouroboros/helpers/bounding_boxes.py:6 — DEFAULT_SPLIT_THRESHOLD = 0.9 is not user-configurable through BoundingBoxParams (only max_depth and target_slices_per_box are). Is that deliberate, or should it also be surfaced through bounding_box_params?
10. python/ouroboros/helpers/options.py:78 — chunk_size: int = 160 on BackprojectOptions. What's the rationale for 160 specifically? Would help users tune it if we can quote the reasoning in the docs (peak-memory budget, cache alignment, etc.).
11. python/ouroboros/helpers/mem.py:14 — MEM_INTERVAL_TIMER = 1.0. It's both the memory-log poll interval and the pre-exit sleep in exit_cleanly. Is coupling these deliberate, or would separating them (a log interval and a shutdown grace period) be clearer?
12. python/compose.yml:15, python/compose.dev.yml:28, and scripts/prepare-production-server.mjs:52 — shm_size: 64gb is hard-coded in all three compose sources. Is 64 GB a measured worst-case for the shipping pipelines, and should it be env-overridable at packaging time (OUROBOROS_SERVER_SHM_SIZE) for constrained hosts?
13. python/Dockerfile:1 and python/Dockerfile-prod:5 — thehale/python-poetry:2.1.3-py3.11-slim. Is Poetry 2.1.3 / Python 3.11 an intentional long-term pin, or a "bump when we next touch this" pin? Documenting the policy would help downstream forks.
14. scripts/prepare-package-flavor.mjs:7-16 — productionPluginPins for neuroglancer and autoseg are duplicated in the fallback filename builders neuroglancerArtifactForTag / autosegArtifactForTag. Are these pins meant to move together on every release, and is there a preferred single-file-edit workflow when bumping them?
15. python/ouroboros/helpers/slice.py:12 — INDEXING = "xy". Assumed to be a NumPy meshgrid indexing convention. Is this ever expected to become "ij" for any code path, and is it worth pulling out as a documented invariant instead?

[tavateva]

Thanks for the answers. Landed as two changes:

• Code side: PR #109 - chore(constants): named ports w/ env override, tighten iframe allowlist, split memory interval, env-configurable shm_size. Covers Q1, Q4, Q6, Q7, Q11, and Q12. Q6 runtime drift check was scoped down to a TODO(#107) on the TS side because ServerContext does not currently expose baseURL to non-fetch-hook callers; the Python enum + GET /step-names endpoint is landed.
• Docs side: one additional commit on this branch (docs/107-gh-pages-refresh), commit 9a58cb9 - docs: address #108 follow-up answers (constants renames, invariants, rationales) (#107). Covers Q1 renames, the Q2 VOLUME invariant call-out, Q7 env vars, Q8 "Why 'main'", Q9 non-user-surfacing note on DEFAULT_SPLIT_THRESHOLD, Q10 chunk_size=160 rationale in your words, Q11 removal of the MEM_INTERVAL_TIMER entry, Q12 shm_size rationale + OUROBOROS_SERVER_SHM_SIZE, Q13 pin policy, and Q14 bump-workflow note.

Q3, Q5, Q15 were "fine" / "no" and needed no action.

Verification on the code side: npm run typecheck passes; docker-compose config succeeds on both python/compose.yml and python/compose.dev.yml with the default substitution and with OUROBOROS_SERVER_SHM_SIZE=128gb; node scripts/prepare-production-server.mjs generates the expected shm_size (64gb default, 16gb under override). npm run lint was not runnable - the repo's .eslintrc predates ESLint 9 and fails config discovery; unrelated to this change. Happy to file a separate lint-config-migration issue if useful.