docs: add CONTRIBUTING.md, CHANGELOG.md, and JSDoc to entire codebase

Add docs/CONTRIBUTING.md covering the build system, dev workflow, all
npm scripts, how to add new native host message types, code style, and
debugging guidance.

Add CHANGELOG.md at the project root documenting all features and fixes
across the 1.0.0 release.

Add JSDoc (@param, @returns) to all previously undocumented exported
functions across 35 JS files:
- native-host/holesail-manager/ (index, virtual-hosts, service-tunnels,
  servers, port-allocator)
- native-host top-level managers (startup, connect-proxy, https-proxy,
  certificate-authority, ssh-manager, rdp-manager)
- extension/background/ (logs, native-messaging, proxy, message-router)
- extension/dashboard/core/ (utils, navigation, init)
- extension/dashboard/ui/ (modal, toast, state-tag)
- extension/dashboard/pages/ (all 10 page files)
- extension/dashboard/refresh.js, events.js
- extension/dashboard/data/hostname-validator.js
- scripts/ (build-host, run-install)

native-host/holesail-manager/service-tunnels.js

@@ -28,6 +28,14 @@ let _getAutoReconnect = null;
 const RECONNECT_BASE_MS = 5000;
 const RECONNECT_MAX_MS = 120000;
 
+/**
+ * Inject shared dependencies from the parent holesail-manager.
+ * Must be called once before any other function in this module.
+ * @param {Function} saveStateFn - Callback that persists the current state to disk.
+ * @param {Function} emitFn - Callback to emit tunnel lifecycle events to the extension.
+ * @param {Function} getReadyTimeoutMsFn - Returns the configured ready-timeout in ms (0 = no timeout).
+ * @param {Function} getAutoReconnectFn - Returns whether auto-reconnect is enabled.
+ */
 function init(saveStateFn, emitFn, getReadyTimeoutMsFn, getAutoReconnectFn) {
   _saveState = saveStateFn;
   _emit = emitFn;
@@ -53,6 +61,10 @@ function _scheduleSvcReconnect(tunnelId) {
   }, delay);
 }
 
+/**
+ * Advance the service tunnel ID counter to avoid collisions after a restart.
+ * @param {number} loadedNextServiceTunnelId - The `nextServiceTunnelId` value read from state.json.
+ */
 function applyLoaded(loadedNextServiceTunnelId) {
   if (loadedNextServiceTunnelId > nextServiceTunnelId) nextServiceTunnelId = loadedNextServiceTunnelId;
 }
@@ -71,6 +83,16 @@ function readyWithTimeout(hs, label) {
   });
 }
 
+/**
+ * Start a service tunnel, connecting a remote Holesail peer to a local port.
+ * Any TCP client can connect to `127.0.0.1:<localPort>` directly (no HTTP proxy).
+ * @param {object} payload
+ * @param {string} payload.label - Human-readable label (required).
+ * @param {string} payload.hsUrl - The hs:// key of the remote peer (required).
+ * @param {number} payload.localPort - Local port to bind (1–65535, required).
+ * @param {string} [payload.tunnelId] - Optional explicit ID; auto-generated if omitted.
+ * @returns {Promise<{ok: boolean, tunnelId?: string, label?: string, hsUrl?: string, localPort?: number, state?: string, error?: string}>}
+ */
 async function startServiceTunnel(payload) {
   if (!Holesail) return { ok: false, error: 'Holesail module not installed' };
   const { label, hsUrl, localPort } = payload;
@@ -118,6 +140,12 @@ async function startServiceTunnel(payload) {
   }
 }
 
+/**
+ * Stop a service tunnel, close the Holesail connection, and remove it from state.
+ * @param {object} payload
+ * @param {string} payload.tunnelId - ID of the service tunnel to stop.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
 async function stopServiceTunnel(payload) {
   const { tunnelId } = payload;
   debugLog('stopServiceTunnel: id=', tunnelId);
@@ -131,6 +159,10 @@ async function stopServiceTunnel(payload) {
   return { ok: true };
 }
 
+/**
+ * Return a snapshot of all service tunnels (including errored/closed ones).
+ * @returns {Array<{id: string, label: string, hsUrl: string, localPort: number, state: string, createdAt: number}>}
+ */
 function getServiceTunnels() {
   const list = [];
   for (const [id, t] of serviceTunnels) {
@@ -141,6 +173,11 @@ function getServiceTunnels() {
 
 function getNextServiceTunnelId() { return nextServiceTunnelId; }
 
+/**
+ * Cancel all reconnect timers and close all service tunnel connections.
+ * Called during native host shutdown.
+ * @returns {Promise<void>}
+ */
 async function cleanupServiceTunnels() {
   for (const [, t] of serviceTunnels) {
     if (t.reconnectTimer) { clearTimeout(t.reconnectTimer); t.reconnectTimer = null; }