Development and distribution

The private source repository owns implementation and the engineering contract in docs/spec.md. Public user guides live in twocentinc/oss, under docs/content/docs/guildscribe/. Source access is required to contribute to the implementation. Keep README as a short entry point into these guides.

With Node.js 22.12+, FFmpeg, and ffprobe installed:

npm ci
npm run check
npm test
npm run test:package

Tests use temporary homes and fabricated data. Do not start a live daemon, send Discord messages, execute configured hooks, or install a LaunchAgent during verification. The package test installs a tarball with lifecycle scripts disabled, explicitly rebuilds its native SQLite dependency, and checks the executable and database worker.

ContractsCopy Anchor Link

src/commands.ts owns command discovery; src/protocol.ts owns envelopes, request/result schemas, versions, and exits. Recording validators check saved files. src/databaseWorker.ts handles SQLite migrations and work; src/storage.ts is the typed access layer.

Generate current snapshots from the runtime definitions. Keep archived versions unchanged. npm test checks them. Run npm run contracts:update only for an intentional versioned contract change. A package version bump alone does not authorize a frozen schema change.

Copy reviewed command-catalog.json and schemas.json snapshots into oss contracts/guildscribe/ when contracts change, and record the source revision in its README. The public reference renders these files.

src/macosLaunchAgent.ts renders and installs plists, calls launchctl, and parses status. src/startup.ts supplies Guildscribe’s label, wrapper, working directory, and log paths. src/history.ts implements local queries, exports, transcription retry requests, and database maintenance.

DistributionCopy Anchor Link

npm run package:npm

This writes a tarball and SHA-256 sidecar under ignored artifacts/. Packages include compiled JavaScript, the engineering specification, operational scripts, README, and license. Runtime data and credentials are excluded. Native SQLite installation requires a compatible runtime/prebuilt binary or native build tools.

Tags matching v<package-version> publish attested tarballs and checksums after verification. Ordinary CI is read-only. npm publication is a separate manual step; private GitHub releases require access.

scripts/upgradeGlobal.sh upgrades a global install and refreshes its LaunchAgent; check its package/source arguments while npm publication is unavailable. scripts/uninstallGlobal.sh removes the agent and global package while preserving the runtime home. Both reject root execution.

Documentation checksCopy Anchor Link

From oss:

cd docs
npm ci
npm run types:check
NEXT_PUBLIC_BASE_PATH=/oss npm run build

Check links and generated references. Keep planned features out of usage instructions: the engineering spec's asynchronous transcription callbacks are not implemented commands.