chore: scrubbing the repo for alignment

Author: centerorbit

.github/workflows/ci.yml

@@ -19,17 +19,18 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: '22.14.0'
+          cache: npm
 
       - name: Install commit tooling
-        run: npm install
+        run: npm ci
 
       - name: Lint commits
         shell: bash
         run: |
           git fetch --no-tags --prune --unshallow || true
           base=$(git merge-base origin/main HEAD || echo HEAD~20)
-          npx commitlint --from="$base" --to=HEAD
+          npx --no-install commitlint --from="$base" --to=HEAD
 
   test:
     name: test (${{ matrix.name }})

.github/workflows/release.yml

@@ -33,12 +33,13 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: '22.14.0'
+          cache: npm
 
       - name: Install release tooling
-        run: npm install
+        run: npm ci
 
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: npx semantic-release
+        run: npx --no-install semantic-release

README.md

@@ -6,6 +6,9 @@
 
 The result is intentionally simple: every node can serve the UI, every node shares fresh load metrics with its peers, and the browser can be hot-potatoed around the cluster without a central coordinator.
 
+Deeper docs live in `docs/`; this README stays focused on quick start and common
+deployment paths.
+
 ## Features
 
 - **Cluster htop view**: CPU, memory, load, freshness, and offline status for every known node.
@@ -99,6 +102,7 @@ Templates live in `deploy/` for common ways to keep Pulse running:
 | macOS launchd | `deploy/launchd/com.offpeakengineer.pulsed.plist` |
 | Windows service | `deploy/windows/install-service.ps1` using NSSM |
 | Kubernetes | `deploy/kubernetes/pulsed.yaml` |
+| Helm | `helm/pulsed` |
 | Ansible local binary | `deploy/ansible/install-pulsed.yml` |
 | Ansible release binary | `deploy/ansible/install-release-pulsed.yml` |
 | Traefik to bare metal | `deploy/traefik/bare-metal-node.yaml` |

deploy/ansible/install-psstd.yml deploy/ansible/install-pulsed.ymldeploy/ansible/install-psstd.yml renamed to deploy/ansible/install-pulsed.yml

@@ -0,0 +1,54 @@
+# Terminology
+
+This file keeps the concept vocabulary grounded enough to implement without
+turning it into a named product taxonomy too early.
+
+## Node
+
+A node is an addressable observer. Today that is usually a running `pulsed`
+process on a host. In the broader model, a node can also represent a pod,
+container, service, device, bus, orchestrator, availability zone, region, or
+other scoped body.
+
+Nodes may have child nodes, but the relationship is hierarchical. A node path is
+a rooted parent/child address, not an arbitrary graph.
+
+## Body Node
+
+A body node is an external-facing boundary for a scope. Examples include a pod,
+host, orchestrator, zone, or region. Body nodes decide which internal details
+are exposed, summarized, hidden, or forwarded.
+
+## Internal Node
+
+An internal node is a child inside a local scope. Internal nodes may share more
+detail through a local loopback mesh because they are inside the same boundary.
+
+## Observation
+
+An observation is something a node knows, senses, sees, hears, or chooses to
+share. Observations should carry source identity, time, category, path, and
+freshness metadata.
+
+## Enumeration
+
+Enumeration answers "what exists?" before a caller asks for a payload. The core
+index dimensions are:
+
+- when: timeslice or freshness window
+- who: source node identity
+- where: node path or scoped body
+- what: structure, parameter, metric, tag, or resource kind
+- how: current, historical, stale, direct, heard, re-shared, signed, unsigned
+
+## Queryable Resource
+
+A queryable resource is a tagged thing a node can advertise and another node can
+request. Themes are the smallest useful example: a node can enumerate available
+themes and share one when policy allows it.
+
+## Trust
+
+Trust is local receiver interpretation, not global truth. Signature status,
+source distance, scope, freshness, and operator policy should remain separate in
+data even when the UI summarizes them.