Operations Runbook

status: verified on 2026-08-30

The receipts below were observed against the production adapter-node service, nginx ingress, Quartz publication, and public browser surfaces.

Application build

status: verified

The production gate was:

npm run check && npm run build

svelte-check completed across 4,826 files with 0 errors and 0 warnings. Vite completed both SSR and client builds, and adapter-node emitted build/index.js. The lockfile SHA-256 was 91c31bb686a3c3412e8883cbb0dfc4d8b3551286f099cd1f798ee8198b029a47. The service was restarted after the final production build.

Runtime service

status: verified

The source unit deploy/bits.service is installed at /etc/systemd/system/bits.service, enabled for multi-user.target, and active. It runs as loca:loca from the project root with:

/usr/bin/node build/index.js

The unit pins HOST=127.0.0.1, PORT=51500, BITS_DATA_DIR=/home/loca/bits, and BODY_SIZE_LIMIT=2M. It uses Restart=on-failure, gives the service a single writable boundary at /home/loca/bits, and applies the hardening declared in the source unit.

Observed startup status was active (running) with the journal line:

Listening on http://127.0.0.1:51500

Direct loopback probes of / and /builder both returned 200.

Builder persistence

status: verified

The deployed endpoint implements GET /api/builder/session and POST /api/builder/session with { spec, messages }, persisted as /home/loca/bits/builder/default.json.

The live contract probe observed:

• initial GET: 200;
• valid POST: 200;
• second GET: 200 with byte-equivalent JSON state;
• malformed state: 400;
• unsupported spec version: 400; and
• a body above 1 MiB: 413 at the nginx edge.

The service user successfully persisted the non-secret builder state through the configured writable data boundary.

Reverse proxy and TLS

status: verified

The canonical source deploy/bits.nginx.conf is installed as /etc/nginx/sites-available/bits.loca.zone and enabled from sites-enabled. nginx -t reported successful syntax and configuration validation.

• bits.loca.zone proxies to http://127.0.0.1:51500.
• wiki.bits.loca.zone serves /home/loca/dev/wikis/bits/current.
• Plain HTTP redirects to HTTPS.
• One Let’s Encrypt certificate covers both hosts.
• Issuer: C=US, O=Let's Encrypt, CN=YE1.
• Expiry: 2026-11-28 20:29:59 UTC.

External HTTPS probes returned 200 for the application root, builder, wiki root, and wiki component catalog.

Quartz build and publication

status: verified

The Multi-Wiki Grid consumes the project-owned inputs through:

/home/loca/dev/wikis/bits/content -> /home/loca/dev/bits/q5vault
/home/loca/dev/wikis/bits/quartz.config.yaml -> /home/loca/dev/bits/quartz.config.bits.yaml

Publication used:

/home/loca/dev/wikis/build.sh bits

SSOT validation passed. Quartz parsed 61 Markdown files, filtered out none, and emitted 178 files before the wrapper atomically advanced current. The expected warning that this standalone vault is not inside a Git repository does not affect publication.

Live application probes

status: verified

The public application received a browser-level verification pass:

• the home page rendered the intended catalog with all 46 registry entries;
• a route sweep fetched all 46 /components/<slug> URLs with 200 and no failures;
• the Accordion demo expanded its first item and revealed its copyable Svelte source;
• /builder installed the relay and set data-bits-builder="ready";
• window.bitsBuilder.blocks() returned 22 registered blocks;
• a human chat message reached ask();
• two valid operations added a visible “Settings” heading and checked “Dark mode” switch;
• say() completed the chat turn and left zero pending messages;
• an invalid remove operation returned a structured missing-node error;
• undo changed the root count from 3 to 2, and redo restored it to 3; and
• exported source contained the Bits UI Switch implementation.

Desktop and responsive screenshots were inspected. The desktop palette, chat, canvas, inspector, and generated controls were coherent with no confirmed clipping or overlap.

Live wiki probes

status: verified

The public wiki root and component catalog returned 200. A real Chromium session rendered the Quartz Explorer, search control, article, graph control, table of contents, and footer. The page contained no project host paths. The catalog contains the same 46 rows and slugs as src/lib/showcase/registry.ts, and the application route sweep independently confirmed every corresponding URL.

2026-08-31 isolated local production-build verification

status: verified in an isolated local production build; not production

These current receipts were collected against the local production build and local browser only. They do not establish a deployment, publication, public-host result, or live-production state. The dated 2026-08-30 sections above remain the historical production receipts.

Local build gate

• npm run check: 4,827 files, 0 errors, 0 warnings.
• npm run build: Vite SSR and client builds completed successfully, followed by adapter-node success.

Measured local surfaces

Local browser proofs

• Hover opened the tooltip immediately with state instant-open; keyboard focus also made the tooltip visible.
• / focused component search, and date picker filtered the registry to exactly one result.
• All 46 component routes returned 200. Each route carried its exact local guide link, with zero primary upstream-documentation anchors.
• The relay probe enumerated ten public API members—the version literal plus nine callable methods, including reportActivity—and blocks() returned 22 block records.
• A valid two-operation batch succeeded.
• Removing a missing id failed with structured errors and matching error activity.
• An agent reply resolved the pending request.
• Undo changed the root count from 1 → 0; redo changed it from 0 → 1.
• Exported source contained the requested heading.
• Reload restored the title and root from server data, restored the conversation from the server session, and restored activity from local storage. The server payload remained { spec, messages }; activity remained under bits-builder:activity:v1.
• An activity input containing the unknown chainOfThought field was rejected.
• At the mobile viewport, exactly two horizontal scrollers were present with no page-level horizontal overflow; the canvas preceded the inspector; the workspace expanded and collapsed; and the activity tab remained usable.

Activity-status overflow correction

The local browser pass discovered that an .sr-only activity-status node extended beyond the body and inflated page scroll height to 1,564 px. After the fix, scroll height returned to the correct 1,082 px, no hidden status node extended beyond the body, and the populated builder had no horizontal overflow.

Canvas-dominance correction

The final desktop review measured the builder canvas region at 1,136 × 575 px in a 1,440 × 1,000 viewport. All 22 block controls occupied one palette row, the inspector was 288 px wide, the agent workspace remained 224 px high, page height remained 1,082 px, and there was no horizontal overflow.

2026-08-31 production release receipts

The authorized application release restarted bits.service; the immediate systemd readback was active.

Live Chromium then verified:

• https://bits.loca.zone/components rendered the compact 46-link picker with 867 body characters, 1,264 px page height, a working search input, and no sidebar;
• the exhaustive 46-route sweep returned { count: 46, failures: [] }, meaning every component route returned 200, contained its exact local guide URL, and exposed no primary upstream documentation anchor;
• https://bits.loca.zone/builder exposed all ten relay members, including reportActivity, and all 22 block records;
• the live desktop canvas measured 1,136 × 575 px, all block controls occupied one palette row, the inspector measured 288 px, and there was no horizontal overflow.

The authorized wiki publication passed SSOT validation, parsed 61 Markdown inputs, and emitted 178 files. Live Chromium received 200 and the expected release text from the wiki root, component catalog, Build Process Log, Operations Runbook, and /builder/relay-protocol. The relay protocol route is extensionless and has no trailing slash.

Rollback

status: pending verification

Before declaring deployment complete, record the exact application and wiki rollback procedures, the immutable targets they restore, and one non-destructive rollback validation. Do not infer rollback capability merely because an older artifact exists.

Current receipt: no rollback has been exercised.

loca.zone · bits.loca.zone · SvelteKit · Quartz